From 6f351d067a5ba864e3bb17aac7d53ea50bf7c4df Mon Sep 17 00:00:00 2001 From: MrSpaar Date: Fri, 21 Feb 2025 02:33:32 +0100 Subject: [PATCH] chore: wiki easier to understand --- doc/pages/deployment.md | 4 ++-- doc/pages/extensions.md | 18 +++++++----------- doc/pages/extensions/sass.md | 4 ++-- doc/pages/extensions/sitemap.md | 14 +++++++------- doc/pages/extensions/tailwind.md | 6 +++--- doc/pages/features/code.md | 7 ++++++- doc/pages/features/spa.md | 8 ++++---- doc/pages/features/templating.md | 9 +++------ doc/pages/features/toc.md | 7 +++++-- doc/pages/index.md | 4 ++-- doc/scss/code.scss | 7 ++++++- 11 files changed, 47 insertions(+), 41 deletions(-) diff --git a/doc/pages/deployment.md b/doc/pages/deployment.md index 79eb7e5..38a4a84 100644 --- a/doc/pages/deployment.md +++ b/doc/pages/deployment.md @@ -2,7 +2,7 @@ [name]: # (Deployment) [description]: # (How to setup automatic Github Pages deployment) -Github-SPA includes a Github Actions workflow to automatically deploy a static website to Github Pages. +Github-SPA comes with a Github Actions workflow that automatically deploys your website to Github Pages. To enable it, go to your repository's settings and choose `Github Actions` as source in the `Pages` section: ![Enable Github Pages](/static/gh-pages.webp){: width="681" height="469" } @@ -55,4 +55,4 @@ jobs: ``` > [!WARNING] -> You'll need to change `path: './generated'` if you overridden `dist_path` in your `config.ini` file. +> You'll need to change `path: './generated'` if you overridden `dist_path` in your `config.ini` file. diff --git a/doc/pages/extensions.md b/doc/pages/extensions.md index 26c6210..adb1833 100644 --- a/doc/pages/extensions.md +++ b/doc/pages/extensions.md @@ -2,13 +2,9 @@ [name]: # (Extensions) [description]: # (Documentation on markdown_spa's extension system) -`markdown_spa` has a simple extension system that allows you to add custom functionality to your site. -To install an extension, simply run the following command: -```bash -markdown_spa install -``` +`markdown_spa` has a simple extension system that allows you to add custom features. +To install an extension, simply run the following command: `markdown_spa install `. -This will install the extension globally for your user. `markdown_spa` will automatically load all extensions in the `config.ini` file: ```ini [extension-name] @@ -32,7 +28,7 @@ class MyExtension(Extension): # if is_path=True, os.path.exists will be called on the value # if is_template=True, the template path will be prepended to the checked path } - + @property def TO_WATCH(self) -> List[str]: # Any changes to these files will trigger a MyExtension.render @@ -56,12 +52,12 @@ Dependencies will be automatically installed and that part of the initialization - Option values are prompted to the user - The `config.ini` file is updated with the user's input -## Make an extension available to the user +## Make an extension available to anyone -Every `markdown_spa` extension must be a Python module that contains a class that inherits from `markdown_spa.Extension` +Every `markdown_spa` extension must be a Python module that contains a class that inherits from `markdown_spa.Extension` (class name = extension name). -Here is a minimal example of an extension: +Here is a minimal Markdown SPA extension called `MyExtension`: - File structure: ``` @@ -79,4 +75,4 @@ class MyExtension(Extension): - Users can then install the extension with : ```bash markdown_spa install MyExtension -``` \ No newline at end of file +``` diff --git a/doc/pages/extensions/sass.md b/doc/pages/extensions/sass.md index 630a2aa..5524430 100644 --- a/doc/pages/extensions/sass.md +++ b/doc/pages/extensions/sass.md @@ -4,7 +4,7 @@ The SASS extension allows you to use SASS in your project. -To add it to an existing project, run `markdown_spa add SASS`, there are two options: +To add it to an existing project, run `markdown_spa add SASS`, there are two `config.ini` options: - `source_path`: The path to the directory containing your SASS files - `main_path`: The path to the main SASS file (relative to project root) @@ -14,7 +14,7 @@ To add it to an existing project, run `markdown_spa add SASS`, there are two opt ## Manual configuration -First, modify your `config.ini` file to add the following section: +First, add the following section to `config.ini`: ```ini [SASS] source_path = scss diff --git a/doc/pages/extensions/sitemap.md b/doc/pages/extensions/sitemap.md index ae5d81b..4f2c17f 100644 --- a/doc/pages/extensions/sitemap.md +++ b/doc/pages/extensions/sitemap.md @@ -2,23 +2,23 @@ [name]: # (Sitemap) [description]: # (Automatic sitemap and robots.txt generation) -`Sitemap` comes with `markdown_spa` by default, it allows you to generate a `sitemap.xml` and `robots.txt` files for your website. +`Sitemap` comes with `markdown_spa` by default, it allows you to automatically generate `sitemap.xml` and `robots.txt`. -To add it to an existing project, run `markdown_spa add Sitemap`, there are two options: +To add it to an existing project, run `markdown_spa add Sitemap`, there are two `config.ini` options: -- `sitemap`: The path to the `sitemap.xml` template (relative to templates directory) -- `robots`: The path to the `robots.txt` template (relative to templates directory) +- `sitemap`: The path to the `sitemap.xml` template (relative to the templates directory) +- `robots`: The path to the `robots.txt` template (relative to the templates directory) ## Manual configuration -First, modify your `config.ini` file to add the following section: +First, add the following section to `config.ini`: ```ini [Sitemap] sitemap = sitemap.xml robots = robots.txt ``` -You can then create the `sitemap.xml` and `robots.txt` files in your templates directory: +You can then create both templates: - `robots.txt` : ``` @@ -46,4 +46,4 @@ Disallow: ``` These are the default templates that comes with blank projects, you can customize them as you wish. -A `sitemap.xml` and `robots.txt` will be generated at the root of your website. +`sitemap.xml` and `robots.txt` will be generated at the root of your website. diff --git a/doc/pages/extensions/tailwind.md b/doc/pages/extensions/tailwind.md index 4c092b6..1d6fb6e 100644 --- a/doc/pages/extensions/tailwind.md +++ b/doc/pages/extensions/tailwind.md @@ -4,7 +4,7 @@ The Tailwind extension allows you to use Tailwind CSS in your templates and markdown files. -To add it to an existing project, run `markdown_spa add Tailwind`, there are two options: +To add it to an existing project, run `markdown_spa add Tailwind`, there are two `config.ini` options: - `config_file`: The path to the Tailwind config file (relative to project root) - `input_file`: The path to the input CSS file (optional, relative to project root) @@ -14,7 +14,7 @@ To add it to an existing project, run `markdown_spa add Tailwind`, there are two ## Manual configuration -First, modify your `config.ini` file to add the following section: +First, add the following section to `config.ini`: ```ini [Tailwind] input_file = assets/tailwind.css @@ -31,7 +31,7 @@ module.exports = { ``` You can now use tailwind in your templates and markdown files. -Optionally, you can have an input CSS file, it just needs the following content: +Optionally, you can have an input CSS file: ```css @tailwind base; @tailwind components; diff --git a/doc/pages/features/code.md b/doc/pages/features/code.md index 285664a..749433f 100644 --- a/doc/pages/features/code.md +++ b/doc/pages/features/code.md @@ -2,7 +2,12 @@ [name]: # (Syntax Highlighting) [description]: # (Syntax highlighting in code blocks) -Syntax highlighting in code blocks is done using the [codehilite](https://python-markdown.github.io/extensions/code_hilite/) and [fenced_code](https://python-markdown.github.io/extensions/fenced_code_blocks/) extensions. You can create code blocks (language name can be deduced): +Syntax highlighting in code blocks comes pre-installed and is done using the [codehilite](https://python-markdown.github.io/extensions/code_hilite/) and [fenced_code](https://python-markdown.github.io/extensions/fenced_code_blocks/) extensions. + +> [!NOTE] +> All available themes are downloadable [here](https://pygments.org/styles/) and CSS files should be in your assets folder. + +You can create code blocks (language name can be deduced): - With a shebang (to show line numbers) ``` { .markdown linenos=true linenostart=1 } diff --git a/doc/pages/features/spa.md b/doc/pages/features/spa.md index d2b95be..e5b5876 100644 --- a/doc/pages/features/spa.md +++ b/doc/pages/features/spa.md @@ -2,7 +2,7 @@ [name]: # (Single Page App) [description]: # (Control how pages are loaded) -Any blank project comes with `markdown_spa.js` in the assets folder. This simple script controls how pages are loaded and what content is updated. +Any project comes with `markdown_spa.js` in the assets folder. This simple script controls how pages are loaded and what content is updated. Whenever a link to another page is clicked or a popstate event is fired, the script will: - Call the `preFetch()` function if it exists @@ -12,14 +12,14 @@ Whenever a link to another page is clicked or a popstate event is fired, the scr > [!TIP] > You can override the `preFetch()` and `postFetch()` functions to add custom logic. -The default strategy is to fetch the new page as HTML and replace the entire document. However, if you want to load only a portion of the page, you can use the JSON strategy: +By default the new page if fetched and replaces the entire document. However, if you want to modify specific parts of the page, you can use the JSON mode: - Enable JSON in the `config.ini` file: ```ini [GENERATOR] json = true ``` -- Along with each page, a JSON file will be generated: +- A JSON file will be generated for each page ```json { "uri": "/uri/to/page", @@ -27,7 +27,7 @@ json = true "any_meta_tag": "..." } ``` -- Create a `updateWithJSON` function before the `markdown_spa.js` script: +- Add a `updateWithJSON` function to your website: ```js function updateWithJSON(json) { // Update the page with the JSON data, for instance: diff --git a/doc/pages/features/templating.md b/doc/pages/features/templating.md index 0b61290..88cc11d 100644 --- a/doc/pages/features/templating.md +++ b/doc/pages/features/templating.md @@ -2,7 +2,7 @@ [name]: # (Templating) [description]: # (How to use jinja2 templates in a markdown_spa project) -`markdown_spa` uses [jinja2](https://jinja.palletsprojects.com/en/3.0.x/), allowing you to create a base template that will be used for all pages. +`markdown_spa` uses [jinja2](https://jinja.palletsprojects.com/en/3.0.x/), allowing you to create a base template for all generated pages. By default, the following variables are available: | Variable | Available in | Description | @@ -12,10 +12,7 @@ By default, the following variables are available: | `{{ assets_path }}` | Base and nav templates, HTML pages | Path to the assets directory | | `{{ page_content }}` | Base template | HTML content of each markdown file | -> [!WARNING] -> Pages can be HTML or Markdown files, but the variables are only available in HTML files. - -To add your own variables, you can add attributes at the top of **each** file: +To add your own variables, you can add attributes at the top of **each** markdown file: ```md [title]: # (This is a title) [summary]: # (This is a description) @@ -23,7 +20,7 @@ To add your own variables, you can add attributes at the top of **each** file: This is the actual content of the rendered page. ``` -Then, in the base template, variables with the same name will be available: +Then, in the base template, variables will be accessible through the `meta` variable: ```html

{{ meta.title }}

diff --git a/doc/pages/features/toc.md b/doc/pages/features/toc.md index d70baea..0d39a00 100644 --- a/doc/pages/features/toc.md +++ b/doc/pages/features/toc.md @@ -2,7 +2,7 @@ [name]: # (Table of Contents) [description]: # (Automatically generated table of contents) -The table of contents at the side of this page was automatically generated from the `nav_template` in the `config.ini` file. +The table of contents at the side of this page was automatically generated by the `nav_template` in the `config.ini` file. In blank projects, the template is the following: ```jinja
    @@ -18,7 +18,7 @@ In blank projects, the template is the following:
``` -Which will render the following HTML: +Which will, for instance, render the following HTML: ```html
  • Main page
    • @@ -29,3 +29,6 @@ Which will render the following HTML:
``` + +The for loop will recursively explore your project's file structure and `tree` contains a mapping of pages. +This `tree` variable changes anytime `loop` is called and each `page` has a `meta` and `children` property. diff --git a/doc/pages/index.md b/doc/pages/index.md index e78472a..5c96701 100644 --- a/doc/pages/index.md +++ b/doc/pages/index.md @@ -14,7 +14,7 @@ First, to setup a new project: -- Install the package (once): `pip install markdown_spa` +- Make sure the package is installed: `pip install markdown_spa` - Create a blank project: `markdown_spa init ` The `config.ini` file describes the project structure: @@ -34,4 +34,4 @@ And finally, to build your website you have two options: - Live-reload: `markdown_spa watch ` > [!NOTE] -> If scripts aren't added to `PATH`, you can use `python -m markdown_spa` instead of `markdown_spa`. \ No newline at end of file +> If scripts aren't added to `PATH`, you can use `python -m markdown_spa` instead of `markdown_spa`. diff --git a/doc/scss/code.scss b/doc/scss/code.scss index cb1dd16..2bcf3b4 100644 --- a/doc/scss/code.scss +++ b/doc/scss/code.scss @@ -5,10 +5,15 @@ code { background-color: #f1e9e9; @media (prefers-color-scheme: dark) { - background-color: #404145; + background-color: var(--alternative-background-color); } } +.quote code, +tr:nth-child(2n) code { + background-color: var(--background-color); +} + .codehilite { --content-color: black; --header-color: #f14343;