This commit is contained in:
parent
4f8979ae9b
commit
828a82e5cb
10 changed files with 251 additions and 34 deletions
63
README.md
63
README.md
|
|
@ -28,6 +28,7 @@ For an example of a website built with zona, please see
|
|||
- [Site Layout](#site-layout)
|
||||
- [Templates](#templates)
|
||||
- [Markdown Footer](#markdown-footer)
|
||||
- [RSS Feed Generation](#rss-feed-generation)
|
||||
- [Internal Link Resolution](#internal-link-resolution)
|
||||
- [Syntax Highlighting](#syntax-highlighting)
|
||||
- [Markdown Extensions](#markdown-extensions)
|
||||
|
|
@ -49,6 +50,7 @@ For an example of a website built with zona, please see
|
|||
- Live refresh in browser preview.
|
||||
- `jinja2` template support with sensible defaults included.
|
||||
- Basic page, blog post, post list.
|
||||
- RSS feed generation.
|
||||
- Glob ignore.
|
||||
- YAML frontmatter.
|
||||
- Easily configurable sitemap header.
|
||||
|
|
@ -212,6 +214,17 @@ it's parsed and rendered into HTML, then made available to other templates as
|
|||
the `footer` variable. If `footer.md` is missing but `footer.html` exists, then
|
||||
it's used instead. **Note: links are _not_ resolved in the footer.**
|
||||
|
||||
### RSS Feed Generation
|
||||
|
||||
Zona can also generates an RSS feed containing your blog posts. This feature is
|
||||
disabled by default, and you can enable it in the
|
||||
[configuration](#configuration).
|
||||
|
||||
The default location is a file called `rss.xml` in the content root. All RSS
|
||||
related configuration is specified in `config.yml`. If you plan to use the feed,
|
||||
make sure to replace the placeholder `link`, `title`, `description`, and
|
||||
`author` configuration values before you set `enabled: true`.
|
||||
|
||||
### Internal Link Resolution
|
||||
|
||||
When zona encounters links in Markdown documents, it attempts to resolve them as
|
||||
|
|
@ -309,18 +322,19 @@ YAML frontmatter can be used to configure the metadata of documents. All of them
|
|||
are optional. `none` is used when the option is unset. The following options are
|
||||
available:
|
||||
|
||||
| Key | Type & Default | Description |
|
||||
| ------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `title` | `str` = title-cased filename. | Title of the page. |
|
||||
| `date` | Date string = file modified time. | Displayed on blog posts and used for post_list sorting. |
|
||||
| `show_title` | `bool` = `true` | Whether `metadata.title` should be included in the template. |
|
||||
| `header` | `bool` = `true` | Whether the header sitemap should be rendered. |
|
||||
| `footer` | `bool` = `true` | Whether the footer should be rendered. |
|
||||
| `template` | `str \| none` = `none` | Template to use for this page. Relative to `templates/`, `.html` extension optional. |
|
||||
| `post` | `bool \| none` = `none` | Whether this page is a **post**. `true`/`false` is _absolute_. Leave it unset for automatic detection. |
|
||||
| `draft` | `bool` = `false` | Whether this page is a draft. See [drafts](#drafts) for more. |
|
||||
| `ignore` | `bool` = `false` | Whether this page should be ignored in _both_ `final` and `draft` contexts. |
|
||||
| `math` | `bool` = `true` | Whether the LaTeX extension should be enabled for this page. |
|
||||
| Key | Type & Default | Description |
|
||||
| ------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `title` | `str` = title-cased filename. | Title of the page. |
|
||||
| `description` | `str \| none` = `none` | Description. If omitted, default from [config](#configuration) will be used. |
|
||||
| `date` | Date string = file modified time. | Displayed on blog posts and used for post_list sorting. |
|
||||
| `show_title` | `bool` = `true` | Whether `metadata.title` should be included in the template. |
|
||||
| `header` | `bool` = `true` | Whether the header sitemap should be rendered. |
|
||||
| `footer` | `bool` = `true` | Whether the footer should be rendered. |
|
||||
| `template` | `str \| none` = `none` | Template to use for this page. Relative to `templates/`, `.html` extension optional. |
|
||||
| `post` | `bool \| none` = `none` | Whether this page is a **post**. `true`/`false` is _absolute_. Leave it unset for automatic detection. |
|
||||
| `draft` | `bool` = `false` | Whether this page is a draft. See [drafts](#drafts) for more. |
|
||||
| `ignore` | `bool` = `false` | Whether this page should be ignored in _both_ `final` and `draft` contexts. |
|
||||
| `math` | `bool` = `true` | Whether the LaTeX extension should be enabled for this page. |
|
||||
|
||||
**Note**: you can specify the date in any format that can be parsed by
|
||||
[`python-dateutil`](https://pypi.org/project/python-dateutil/).
|
||||
|
|
@ -374,12 +388,23 @@ useful settings are listed here.
|
|||
Please see the default configuration:
|
||||
|
||||
```yaml
|
||||
base_url: /
|
||||
feed:
|
||||
enabled: true
|
||||
timezone: UTC
|
||||
path: rss.xml
|
||||
link: https://example.com
|
||||
title: Zona Website
|
||||
description: My zona website.
|
||||
language: en
|
||||
author:
|
||||
name: John Doe
|
||||
email: john@doe.net
|
||||
sitemap:
|
||||
Home: /
|
||||
ignore:
|
||||
- .marksman.toml
|
||||
markdown:
|
||||
image_labels: true
|
||||
tab_length: 2
|
||||
syntax_highlighting:
|
||||
enabled: true
|
||||
|
|
@ -392,6 +417,8 @@ build:
|
|||
include_drafts: false
|
||||
blog:
|
||||
dir: blog
|
||||
defaults:
|
||||
description: A blog post
|
||||
server:
|
||||
reload:
|
||||
enabled: true
|
||||
|
|
@ -400,6 +427,15 @@ server:
|
|||
|
||||
| Name | Description |
|
||||
| -------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `feed.enabled` | Whether RSS feed should be generated. **Off by default**. |
|
||||
| `feed.timezime` | Timezone to use for post `pubDate` values. Must be an IANA compliant string. |
|
||||
| `feed.path` | Location of the feed, relative to content root. |
|
||||
| `feed.link` | The base URL of the website. |
|
||||
| `feed.title` | Website title. |
|
||||
| `feed.description` | Website description. |
|
||||
| `feed.language` | String specifying website's language code. |
|
||||
| `author.name` | Your full name. |
|
||||
| `author.email` | Your email address. |
|
||||
| `sitemap` | Sitemap dictionary. See [Sitemap](#sitemap). |
|
||||
| `ignore` | List of paths to ignore. See [Ignore List](#ignore-list). |
|
||||
| `markdown.tab_length` | How many spaces should be considered an indentation level. |
|
||||
|
|
@ -410,6 +446,7 @@ server:
|
|||
| `build.clean_output_dir` | Whether previous build artifacts should be cleared when building. Recommended to leave this on. |
|
||||
| `build.include_drafts` | Whether drafts should be included by default. |
|
||||
| `blog.dir` | Name of a directory relative to `content/` whose children are automatically considered posts. |
|
||||
| `blog.defaults.description` | Default description for blog posts with no `description` in their frontmatter. |
|
||||
| `server.reload.enabled` | Whether the preview server should use [live reload](#live-preview). |
|
||||
| `server.reload.scroll_tolerance` | The distance, in pixels, from the bottom to still count as "scrolled to bottom". |
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue