summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md107
1 files changed, 69 insertions, 38 deletions
diff --git a/README.md b/README.md
index 4686564..df1a974 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ Initially inspired by Roman Zolotarev's [`ssg5`](https://rgz.ee/bin/ssg5) and [`
## Features and to-do
-**NOTE:** WIP, there will be changes that will break the setup.
+**NOTE:** WIP, there will be changes that will break `pyssg` generations/config setup.
- [x] Build static site parsing `markdown` files ( `*.md` -> `*.html`)
- [x] Uses [`jinja`](https://jinja.palletsprojects.com/en/3.0.x/) for templating.
@@ -17,11 +17,12 @@ Initially inspired by Roman Zolotarev's [`ssg5`](https://rgz.ee/bin/ssg5) and [`
- [x] Build `rss.xml` file.
- [ ] Include manually added `*.html` files.
- [x] YAML for configuration file, uses [`PyYAML`](https://pyyaml.org/).
- - [x] Handle multiple "documents". `PyYAML` supports this.
- - [x] More complex directory structure to support multiple subdomains and different types of pages. This is supported by using mupltiple "documents" in the `yaml` config file.
+ - [x] Support for multiple "documents". `PyYAML` supports this. In `pyssg` context, it means it can generate multiple websites (I personally use it for subdomains).
+ - [x] Support for more complex directory structure to support configuration on a per directory basis.
- [x] File checksum checking for modification of files.
- [ ] Option/change to using an SQL database instead of the custom solution.
- [ ] Use external markdown extensions.
+ - [x] So far only extension configuration is for my own extension [pymdvar](https://github.com/luevano/pymdvar).
### Markdown features
@@ -31,7 +32,8 @@ This program uses the base [`markdown` syntax](https://daringfireball.net/projec
- Meta-Data.
- Sane Lists.
- SmartyPants.
-- Table of Contents. (With defaults as specified [here](https://python-markdown.github.io/extensions/toc/))
+- Table of Contents.
+ - With `permalink=True` and `baselevel=2`, for more: [python-markdown toc](https://python-markdown.github.io/extensions/toc/).
- WikiLinks.
- [pymdvar](https://github.com/luevano/pymdvar) (made by me).
- [yafg - Yet Another Figure Generator](https://git.sr.ht/~ferruck/yafg)
@@ -75,7 +77,7 @@ pyssg -i
- Strongly recommended to edit the `rss.xml` template.
-4. Place your `*.md` files somewhere inside the source directory. It accepts sub-directories.
+4. Place your `*.md` files somewhere inside the source directory. It accepts sub-directories. Optionally configure for subdirectories if they are to be treated a bit different.
- Recommended (no longer mandatory) metadata keys that can be added to the top of `.md` files:
@@ -91,7 +93,7 @@ tags: english
etc
```
-- You can add more meta-data keys as long as it is [Python-Markdown compliant](https://python-markdown.github.io/extensions/meta_data/), and these will ve [available as Jinja variables](#available-jinja-variables).
+- You can add more meta-data keys as long as it is [Python-Markdown compliant](https://python-markdown.github.io/extensions/meta_data/), and these will ve [available as Jinja variables](#available-jinja-variables) in the `meta` object (`dict[str, Any]`).
5. Build the `*.html` with:
@@ -99,7 +101,7 @@ tags: english
pyssg -b
```
-- After this, you have ready to deploy `*.html` files.
+- After this, you have ready to deploy `*.html` files from the `dst` directory.
## Config file
@@ -110,7 +112,9 @@ variable: &variable_reference_name "value"
other_variable: !join [*variable_reference_name, "other_value", 1]
```
-Which would produce `other_variable: "valueother_value1"`. Also environment variables will be expanded internally.
+Which would produce `other_variable: "valueother_value1"`. Also **environment variables will be expanded internally**.
+
+**Note**: URL's shouldn't have the trailing slash `/`.
The following is a list of config items that need to be present in the config unless stated otherwise:
@@ -128,37 +132,65 @@ path:
db: !join [*root, "src/", "db.psv"]
url:
main: "https://example.com"
+ # I personally use a "static" url for images/scripts/css/etc, not necessary
+ static: "https://static.example.com"
fmt:
date: "%a, %b %d, %Y @ %H:%M %Z"
- list_date: "%b %d"
- list_sep_date: "%B %Y"
+ list_date: "%b %d" # not necessary
+ list_sep_date: "%B %Y" # not necessary
dirs:
/: # root "dir_path", whatever is sitting directly under "src"
cfg:
- plt: "page.html"
- # the template can be specified instead of just True/False, a default template will used
+ plt: "page.html" # each page template, relative to path/plt
tags: False
index: True
rss: True
sitemap: True
- exclude_dirs: ["articles", "blog"] # optional; list of subdirectories to exclude when parsing the / dir_path
-# below are other example "dir_paths", can be named anything, only the / (above) is mandatory
+ exclude_dirs: ["articles", "blog"] # optional; list of subdirs to exclude when parsing this "dir_path"
+...
+```
+
+So far only [pymdvar](https://github.com/luevano/pymdvar) can be configured by including the following to the config:
+
+```yaml
+exts:
+ pymdvar:
+ variables:
+ SOME_VAR: "some value"
+ some_other_variable: 123
+ enable_env: True # to read environment variables
+```
+
+The config under `dirs` are just per-subdirectory configuration of directories under `src`, which I called "dir_paths" for lack of creativity. Only the `/` "dir_path" is required as it is the config for the root `src` path files. Mandatory config items for each "dir_path":
+
+```yaml
+cfg:
+ plt: "template.html"
+ tags: True
+ index: True
+ rss: True
+ sitemap: True
+ exclude: [] # not necessary
+```
+
+So that extra "dir_paths" can be added under `dirs`:
+
+```yaml
+dirs:
+ /:
+ cfg:
+ ...
articles:
cfg:
- plt: "page.html"
- tags: True
- index: True
- rss: True
- sitemap: True
- blog:
+ ...
+ gallery:
cfg:
- # ...
-...
+ ...
+ etc:
+ ...
```
-The config under `dirs` are just per-subdirectory configuration of directories under `src`. Only the `/` "dir_path" is required as it is the config for the root `src` path files.
-
-The following will be added on runtime:
+The following will be added on runtime to the configuration:
```yaml
%YAML 1.2
@@ -169,20 +201,20 @@ fmt:
info:
version: "x.y.z" # current 'pyssg' version (0.5.1.dev16, for example)
debug: True/False # depending if --debug was used when executing
- force: True/False # depending if --force was used when executing
rss_run_date: # date the program was run, formatted with 'fmt.rss_date'
sitemap_run_date: # date the program was run, formatted with 'fmt.sitemap_date'
...
```
-You can add any other option/section that you can later use in the Jinja templates via the exposed config object. URL's shouldn't have the trailing slash `/`.
+You can add any other option/section that you can later use in the Jinja templates via the exposed config object.
+
## Available Jinja variables
These variables are exposed to use within the templates. The below list is displayed in the form of *variable (type) (available from): description*. `field1/field2/field3/...` describe config file section from the YAML file and option and `object.attribute` corresponding object and it's attribute.
-- `config` (`dict`) (all): parsed config file plus the added options internally (as described in [config file](#config-file)).
-- `dir_config` (`dict`) (all*): parsed dir_config file plus the added options internally (as described in [config file](#config-file)). *This is for all of the specific "dir_path" files, as per configured in the YAML file `dirs.dir_path.cfg` (for exmaple `dirs./.cfg` for the required dir_path).
+- `config` (`dict[str, Any]`) (all): parsed config file plus the added options internally (as described in [config file](#config-file)).
+- `dir_config` (`dict[str, Any]`) (all*): parsed dir_config file plus the added options internally (as described in [config file](#config-file)). *This is for all of the specific "dir_path" files, as per configured in the YAML file `dirs.dir_path.cfg` (for exmaple `dirs./.cfg` for the required dir_path).
- `all_pages` (`list(Page)`) (all): list of all the pages, sorted by creation time, reversed.
- `page` (`Page`) (`page.html`): contains the following attributes (genarally these are parsed from the metadata in the `*.md` files):
- `title` (`str`): title of the page.
@@ -191,20 +223,19 @@ These variables are exposed to use within the templates. The below list is displ
- `summary` (`str`): summary of the page, as specified in the `*.md` file.
- `content` (`str`): actual content of the page, this is the `html`.
- `toc` (`str`): table of contents as taken from `md.toc`.
- - `toc_tokens` (`list(dict)`): table of contents tokens as taken from `md.toc_tokens`.
+ - `toc_tokens` (`list[dict[str, Any]]`): table of contents tokens as taken from `md.toc_tokens`.
- `cdatetime` (`datetime.datetime`): creation datetime object of the page.
- - `cdate` (`method`): method that takes the name of the `fmt.FMT` and applies it to the `cdatetime` object.
+ - `cdate` (`method(FMT: str)`): takes the name of the `fmt.FMT` and applies it to the `cdatetime` object.
- `cdate_rss` (`str`): formatted `cdatetime` as required by rss.
- `cdate_sitemap` (`str`): formatted `cdatetime` as required by sitemap.
- `mdatetime` (`datetime.datetime`): modification datetime object of the page. Defaults to `None`.
- - `mdate` (`method`): method that takes the name of the `fmt.FMT` and applies it to the `mdatetime` object.
+ - `mdate` (`method(FMT: str)`): takes the name of the `fmt.FMT` and applies it to the `mdatetime` object.
- `mdate_rss` (`str`): formatted `mdatetime` as required by rss.
- `mdate_sitemap` (`str`): formatted `mdatetime` as required by sitemap.
- - `tags` (`list(tuple(str))`): list of tuple of tags of the page, containing the name and the url of the tag, in that order. Defaults to empty list.
+ - `tags` (`list[tuple[str]]`): list of tuple of tags of the page, containing the name and the url of the tag, respectively. Defaults to empty list.
- `url` (`str`): url of the page, this already includes the `url/main` from config file.
- - `image_url` (`str`): image url of the page, this already includes the `url/static`. Defaults to the `url/default_image` config option.
- `next/previous` (`Page`): reference to the next or previous page object (containing all these attributes). Defaults to `None`.
- - `meta` (`dict(str, list(str))`): meta dict as obtained from python-markdown, in case you use a meta tag not directly supported, it will be available there.
-- `tag` (`tuple(str)`) (`tag.html`): tuple of name and url of the current tag.
-- `tag_pages` (`list(Page)`) (`tag.html`): similar to `all_pages` but contains all the pages for the current tag.
-- `all_tags` (`list(tuple(str))`) (all): similar to `page.tags` but contains all the tags.
+ - `meta` (`dict[str, list[str]]`): meta dict as obtained from `python-markdown`, in case you use a meta tag not directly supported, it will be available there.
+- `tag` (`tuple[str]`) (`tag.html`): tuple of name and url of the current tag.
+- `tag_pages` (`list[Page]`) (`tag.html`): similar to `all_pages` but contains all the pages for the current tag.
+- `all_tags` (`list[tuple[str]]`) (all): similar to `page.tags` but contains all the tags.