Foliant

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

• Download the compiled binary from this repo's bin directory and use it right away:

  $ ./foliant

• If you have Nim and Nimble installed, install foliant with Nimble:

  $ nimble install foliant

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

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

Options:
  -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
                                    [default: api.md]
  -t --template=<jinja2-template>   Custom Jinja2 template for the Markdown
                                    output.

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.

Example:

$ foliant make pdf

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

$ foliant up MyFile.docx

Convert a Swagger JSON file into Markdown using swagger2markdown (which must be installed with pip install swagger2markdown).

If --output is not specified, the output file is called api.md.

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

Example:

$ foliant s2m http://example.com/api/swagger.json -t templates/swagger.md.j2

Convert Apidoc files into Markdown using apidoc2markdown (which must be installed with pip install apidoc2markdown).

If --output is not specified, the output file is called api.md.

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

Example:

$ foliant a2m /path/to/api_data.json -t templates/apidoc.md.j2

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

.
│   config.json
│   main.yaml
│
├───references
│       ref.docx
│
├───sources
│   │   chapter1.md
│   │   introduction.md
│   │
│   └───images
│           Lenna.png
│
└───templates
        basic.tex
        restream_logo.png

Config file, mostly for Pandoc.

{
  "title": "Lorem ipsum",           // Document title.
  "file_name": "Dolor_sit_amet",    // Output file name. If not set, slugified
                                    // `title` is used.
  "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 set to "auto"
                                    // the version is generated automatically
                                    // based on git tag and revision number.
  "date": "true",                   // Add date to the title page and output
                                    // file name.
  "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:

--- # Contents
chapters:
- 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/:

![](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.

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. By default, Foliant tries to find it in the directory it was invoked in, but you can specify the path to it with --secret option.

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.

Foliant lets you embed seqdiag diagrams.

In order to use thie feature install seqdiag from PyPI:

$ pip install seqdiag

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

```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.

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

$ cat $HOME/.blockdiagrc
[blockdiag]
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).

Make the file executable:

$ chmod +x foliant

Install graphics.def with MikTeX Package Manager (normally invoked with mpm command).