MkDocs backend for Foliant documentation generator.
Project description
# MkDocs Backend for Foliant
MkDocs backend lets you build websites from Foliant projects using [MkDocs](https://mkdocs.org) static site generator.
The backend adds three targets: `mkdocs`, `site`, and `ghp`. The first one converts a Foliant project into a MkDocs project without building any html files. The second one builds a standalone website. The last one deploys the website to GitHub Pages.
## Installation
```bash
$ pip install foliantcontrib.mkdocs
```
## Usage
Convert Foliant project to MkDocs:
```bash
$ foliant make mkdocs -p my-project
✔ Parsing config
✔ Applying preprocessor mkdocs
✔ Making mkdocs with MkDocs
─────────────────────
Result: My_Project-2017-12-04.mkdocs.src
```
Build a standalone website:
```bash
$ foliant make site -p my-project
✔ Parsing config
✔ Applying preprocessor mkdocs
✔ Making site with MkDocs
─────────────────────
Result: My_Project-2017-12-04.mkdocs
```
Deploy to GitHub Pages:
```bash
$ foliant make ghp -p my-project
✔ Parsing config
✔ Applying preprocessor mkdocs
✔ Making ghp with MkDocs
─────────────────────
Result: https://account-name.github.io/my-project/
```
## Config
You don't have to put anything in the config to use MkDocs backend. If it's installed, Foliant detects it.
To customize the output, use options in `backend_config.mkdocs` section:
```yaml
backend_config:
mkdocs:
mkdocs_path: mkdocs
slug: my_awesome_project
use_title: true
use_chapters: true
use_headings: true
mkdocs.yml:
site_name: Custom Title
site_url: http://example.com
site_author: John Smith
```
`mkdocs_path`
: Path to the MkDocs executable. By default, `mkdocs` command is run, which implies it's somewhere in your `PATH`.
`slug`
: Result directory name without suffix (e.g. `.mkdocs`). Overrides top-level config option `slug`.
`use_title`
: If `true`, use `title` value from `foliant.yml` as `site_name` in `mkdocs.yml`. It this case, you don't have to specify `site_name` in `mkdocs.yml` section. If you do, the value from `mkdocs.yml` section has higher priority.
If `false`, you *must* specify `site_name` manually, otherwise MkDocs will not be able to build the site.
Default is `true`.
`use_chapters`
: Similar to `use_title`, but for `pages`. If `true`, `chapters` value from `foliant.yml` is used as `pages` in `mkdocs.yml`.
`use_headings`
: If `true`, the resulting data of `pages` section in `mkdocs.yml` will be updated with the content of top-level headings of source Markdown files.
`mkdocs.yml`
: Params to be copied into `mkdocs.yml` file. The params are passed “as is,” so you should consult with the [MkDocs configuration docs](http://www.mkdocs.org/user-guide/configuration/).
## Preprocessor
MkDocs backend ships with a preprocessor that transforms a Foliant project into a MkDocs one. Basically, `foliant make mkdocs` just applies the preprocessor.
The preprocessor is invoked automatically when you run MkDocs backend, so you don't have to add it in `preprocessors` section manually.
However, it's just a regular preprocessor like any other, so you can call it manually if necessary:
```yaml
preprocessors:
- mkdocs:
mkdocs_project_dir_name: mkdocs
```
`mkdocs_project_dir_name`
: Name of the directory for the generated MkDocs project within the tmp directory.
## Troubleshooting
### Fenced Code Is Not Rendered in List Items or Blockquotes
MkDocs can't handle fenced code blocks in blockquotes or list items due to an [issue in Python Markdown](https://github.com/Python-Markdown/markdown/issues/53).
Unfortunately, nothing can be done about it, either on MkDocs's or Foliant's part. As a workaround, use [indented code blocks](https://daringfireball.net/projects/markdown/syntax#precode).
### Paragraphs Inside List Items Are Rendered on the Root Level
Check if you use **four-space indentation**. [Python Markdown is stern about this point](https://pythonhosted.org/Markdown/index.html#differences).
MkDocs backend lets you build websites from Foliant projects using [MkDocs](https://mkdocs.org) static site generator.
The backend adds three targets: `mkdocs`, `site`, and `ghp`. The first one converts a Foliant project into a MkDocs project without building any html files. The second one builds a standalone website. The last one deploys the website to GitHub Pages.
## Installation
```bash
$ pip install foliantcontrib.mkdocs
```
## Usage
Convert Foliant project to MkDocs:
```bash
$ foliant make mkdocs -p my-project
✔ Parsing config
✔ Applying preprocessor mkdocs
✔ Making mkdocs with MkDocs
─────────────────────
Result: My_Project-2017-12-04.mkdocs.src
```
Build a standalone website:
```bash
$ foliant make site -p my-project
✔ Parsing config
✔ Applying preprocessor mkdocs
✔ Making site with MkDocs
─────────────────────
Result: My_Project-2017-12-04.mkdocs
```
Deploy to GitHub Pages:
```bash
$ foliant make ghp -p my-project
✔ Parsing config
✔ Applying preprocessor mkdocs
✔ Making ghp with MkDocs
─────────────────────
Result: https://account-name.github.io/my-project/
```
## Config
You don't have to put anything in the config to use MkDocs backend. If it's installed, Foliant detects it.
To customize the output, use options in `backend_config.mkdocs` section:
```yaml
backend_config:
mkdocs:
mkdocs_path: mkdocs
slug: my_awesome_project
use_title: true
use_chapters: true
use_headings: true
mkdocs.yml:
site_name: Custom Title
site_url: http://example.com
site_author: John Smith
```
`mkdocs_path`
: Path to the MkDocs executable. By default, `mkdocs` command is run, which implies it's somewhere in your `PATH`.
`slug`
: Result directory name without suffix (e.g. `.mkdocs`). Overrides top-level config option `slug`.
`use_title`
: If `true`, use `title` value from `foliant.yml` as `site_name` in `mkdocs.yml`. It this case, you don't have to specify `site_name` in `mkdocs.yml` section. If you do, the value from `mkdocs.yml` section has higher priority.
If `false`, you *must* specify `site_name` manually, otherwise MkDocs will not be able to build the site.
Default is `true`.
`use_chapters`
: Similar to `use_title`, but for `pages`. If `true`, `chapters` value from `foliant.yml` is used as `pages` in `mkdocs.yml`.
`use_headings`
: If `true`, the resulting data of `pages` section in `mkdocs.yml` will be updated with the content of top-level headings of source Markdown files.
`mkdocs.yml`
: Params to be copied into `mkdocs.yml` file. The params are passed “as is,” so you should consult with the [MkDocs configuration docs](http://www.mkdocs.org/user-guide/configuration/).
## Preprocessor
MkDocs backend ships with a preprocessor that transforms a Foliant project into a MkDocs one. Basically, `foliant make mkdocs` just applies the preprocessor.
The preprocessor is invoked automatically when you run MkDocs backend, so you don't have to add it in `preprocessors` section manually.
However, it's just a regular preprocessor like any other, so you can call it manually if necessary:
```yaml
preprocessors:
- mkdocs:
mkdocs_project_dir_name: mkdocs
```
`mkdocs_project_dir_name`
: Name of the directory for the generated MkDocs project within the tmp directory.
## Troubleshooting
### Fenced Code Is Not Rendered in List Items or Blockquotes
MkDocs can't handle fenced code blocks in blockquotes or list items due to an [issue in Python Markdown](https://github.com/Python-Markdown/markdown/issues/53).
Unfortunately, nothing can be done about it, either on MkDocs's or Foliant's part. As a workaround, use [indented code blocks](https://daringfireball.net/projects/markdown/syntax#precode).
### Paragraphs Inside List Items Are Rendered on the Root Level
Check if you use **four-space indentation**. [Python Markdown is stern about this point](https://pythonhosted.org/Markdown/index.html#differences).
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for foliantcontrib.mkdocs-1.0.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 22efbe4e1754a6c32f8fb08c5e4dca03632334827ec7c67fffeac426d457f8f3 |
|
MD5 | 07ef42a9f3797bfd84be713e417bc3de |
|
BLAKE2b-256 | 1919374b3bf29bb7468a45c96603f8b29dfe05209b1396e171574e4bcfe18e04 |
Close
Hashes for foliantcontrib.mkdocs-1.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c37ee140f813174f57e195431dfb446c32e7db0814c5340611667109aaf46923 |
|
MD5 | fa1463c4ec8ce27653a20bbbfb55e6d5 |
|
BLAKE2b-256 | 13825131b6bde7cc7b3988a97382e97e9b0960d8af53e6134e8f74dd08a82382 |