MkDocs Backend for Foliant¶
MkDocs backend lets you build websites from Foliant projects using MkDocs static site generator.
The backend adds three targets:
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.
$ pip install foliantcontrib.mkdocs
Convert Foliant project to MkDocs:
$ 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:
$ 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:
$ foliant make ghp -p my-project ✔ Parsing config ✔ Applying preprocessor mkdocs ✔ Making ghp with MkDocs ───────────────────── Result: https://account-name.github.io/my-project/
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: mkdocs_path: mkdocs slug: my_awesome_project use_title: true use_chapters: true use_headings: true default_subsection_title: Expand mkdocs.yml: site_name: Custom Title site_url: http://example.com site_author: John Smith
- Path to the MkDocs executable. By default,
mkdocscommand is run, which implies it's somewhere in your
- Result directory name without suffix (e.g.
.mkdocs). Overrides top-level config option
mkdocs.yml. It this case, you don't have to specify
mkdocs.ymlsection. If you do, the value from
mkdocs.ymlsection has higher priority.
false, you must specify
site_namemanually, otherwise MkDocs will not be able to build the site.
- Similar to
use_title, but for
foliant.ymlis used as
true, the resulting data of
mkdocs.ymlwill be updated with the content of top-level headings of source Markdown files.
- Default title of a subsection, i.e. a group of nested chapters, in case the title is specified as an empty string. If
default_subsection_titleis not set in the config, … will be used.
- Params to be copied into
mkdocs.ymlfile. The params are passed “as is,” so you should consult with the MkDocs configuration docs.
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:
preprocessors: - mkdocs: mkdocs_project_dir_name: mkdocs
- Name of the directory for the generated MkDocs project within the tmp directory.
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.
Unfortunately, nothing can be done about it, either on MkDocs's or Foliant's part. As a workaround, use indented code blocks.
Paragraphs Inside List Items Are Rendered on the Root Level¶
Check if you use four-space indentation. Python Markdown is stern about this point.