Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

Markdown-based, Pandoc-powered documentation generator.

Project description


**Foliant** is a documentation generator that builds PDF, Docx, and TeX
documents from Markdown source.

Get It

.. code-block:: shell

$ pip install foliant
$ pip install foliant[s2m] # if you need the Swagger converter


.. code-block:: shell

$ foliant -h
Foliant: Markdown to PDF, Docx, and LaTeX generator powered by Pandoc.

foliant (build | make) <target> [--path=<project-path>]
foliant (upload | up) <document> [--secret=<client_secret*.json>]
foliant (swagger2markdown | s2m) <swagger-location> [--output=<output-file>]
foliant (-h | --help)
foliant --version

-h --help Show this screen.
-v --version Show version.
-p --path=<project-path> Path to your project [default: .].
-s --secret=<client_secret*.json> Path to Google app's client secret file.
-o --output=<output-file> Path to the converted Markdown file
-t --template=<jinja2-template> Custom Jinja2 template for the Markdown

``build``, ``make``

Build the output in the desired format:

- PDF. Targets: pdf, p, or anything starting with "p"
- Docx. Targets: docx, doc, d, or anything starting with "d"
- TeX. Targets: tex, t, or anything starting with "t"
- Markdown. Targets: markdown, md, m, or anything starting with "m"
- Google Drive. Targets: gdrive, google, g, or anything starting with "g"

"Google Drive" format is a shortcut for building Docx and uploading it
to Google Drive.

Specify ``--path`` if your project dir is not the current one.


.. code-block:: shell

$ foliant make pdf

``upload``, ``up``

Upload a Docx file to Google Drive as a Google document:

.. code-block:: shell

$ foliant up MyFile.docx

``swagger2markdown``, ``s2m``

Convert a `Swagger JSON`_ file into Markdown using swagger2markdown_ (which
is installed as an extra with ``pip install foliant[s2m]``).

If ``--output`` is not specified, the output file is called ````.

Specify ``--template`` to provide a custom Jinja2_ template to customize
the output. Use the `default template`_ as a reference.


.. code-block:: shell

$ foliant s2m -t templates/

.. _Swagger JSON:
.. _swagger2markdown:
.. _Jinja2:
.. _default template:

Project Layout

For Foliant to be able to build your docs, your project must conform
to a particular layout::

в”‚ config.json
в”‚ main.yaml
в”‚ ref.docx
в”‚ в”‚
в”‚ в”‚
в”‚ в”‚
в”‚ в””в”Ђв”Ђв”Ђimages
в”‚ Lenna.png


Config file, mostly for Pandoc.

.. code-block:: js

"title": "Lorem ipsum", // Document title.
"second_title": "Dolor sit amet", // Document subtitle.
"lang": "english", // Document language, "russian" or "english."
// If not specified, "russian" is used.
"company": "restream", // Your company name, "undev" or "restream".
// Shown at the bottom of each page.
"year": "2016", // Document publication year.
// Shown at the bottom of each page.
"title_page": "true", // Add title page or not.
"toc": "true", // Add table of contents or not.
"tof": "true", // Unknown
"template": "basic", // LaTeX template to use. Do NOT add ".tex"!
"version": "1.0", // Document version. If not specified
// or set to "auto," the version is generated
// automatically based on git tag and revision number.
"date":"true", // Add date to the title page.
"type": "", // Unknown
"alt_doc_type": "", // Unknown
"filters": ["filter1", "filter2"] // Pandoc filters

For historic reasons, all config values should be strings,
even if they *mean* a number or boolean value.


Contents file. Here, you define the order of the chapters of your project:

.. code-block:: yaml

--- # Contents
- introduction
- chapter1
- chapter2


Directory with the Docx reference file. It **must** be called ``ref.docx``.


Directory with the Markdown source file of your project.


Images that can be embedded in the source files. When embedding an image,
**do not** prepend it with ``images/``:

.. code-block:: markdown

![](image1.png) # RIGHT
![](images/image1.png) # WRONG


LaTeX templates used to build PDF, Docx, and TeX files. The template
to use in build is configured in ``config.json``.

Uploading to Google Drive

To upload a Docx file to Google Drive as a Google document, use
``foliant upload MyFile.docx`` or `foliant build gdrive`, which is
a shortcut for generating a Docx file and uploading it.

For the upload to work, you need to have a so called *client secret* file.
Foliant looks for ``client_secrets.json`` file in the current directory.

Client secret file is obtained through Google API Console. You probably don't
need to obtain it yourself. The person who told you to use Foliant should
provide you this file as well.

Embedding seqdiag Diagrams

Foliant lets you embed `seqdiag <>`__

To embed a diagram, put its definition in a fenced code block:

.. code-block:: markdown

```seqdiag Optional single-line caption
seqdiag {
browser -> webserver [label = "GET /index.html"];
browser <-- webserver;
browser -> webserver [label = "POST /blog/comment"];
webserver -> database [label = "INSERT comment"];
webserver <-- database;
browser <-- webserver;

This is transformed into ``![Optional single-line caption. (diagrams/0.png)``,
where ``diagrams/0.png`` is an image generated from the diagram definition.

Customizing Diagrams

To use a custom font, create the file ``$HOME/.blockdiagrc`` and define
the full path to the font (`ref <>`__):

.. code-block:: shell

$ cat $HOME/.blockdiagrc
fontpath = /usr/share/fonts/truetype/ttf-dejavu/DejaVuSerif.ttf

You can define `other params <>`__
as well (remove ``seqdiag_`` from the beginning of the param name).

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for foliant, version 0.1.7
Filename, size File type Python version Upload date Hashes
Filename, size foliant-0.1.7-py3-none-any.whl (13.6 kB) File type Wheel Python version 3.5 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page