Configuration

All configuration lives in a JSON file that we'll call conf.json. Every path is relative to the directory in which this file lives.

Complete example

Note: JSON cannot contain comments, so this isn't copy-pasteable.

{
  // Include all Markdown files in this directory, ordered
  // alphabetically, but with index.md first if present
  "file_hierarchy": ["*.md"],

  // Name of the project or web site
  "site_title": "My Cool Web Site",

  // Tag line or whatever
  "site_subtitle": "It's very cool.",

  // Version string, if you want it to appear
  "project_version": "1.0",

  // Your name
  "author": "Docs McGee",

  // Place to put HTML files, relative to this file
  "output_dir": "./build",

  // HTML output options
  "html": {

      // Absolute URL of where the site will be uploaded
      "site_url": "http://example.com",

      // Stylesheets to add
      "css_files": ["style.css"],

      // Built-in theme to use (can be null)
      "css_theme": "default",

      // Where to keep stylesheets, images, etc
      "static_dir_name": "static",

      // What to put in the <meta name="description"> tag
      "meta_description": ""
  },

  // Python autodoc options
  "python": {

    // Where to read symbols from.
    // Generate this file with:
    // python3 -m computerwords.source_parsers.python35 \
    //    MODULE_DIR MODULE_NAME
    //    > path/to/symbols.json
    "symbols_path": "symbols.json",
  },

  // Plugins available in $PYTHONPATH
  "plugins": [
    "blah.my_cw_plugin"
  ]
}

Defining table of contents structure with file_hierarchy

The file_hierarchy option, in addition to collecting input files, determines the structure of the table of contents, and therefore the order in which the resulting documents are navigated.

The wording in this section might not be great. If something is confusing, please open a ticket.

Data types

Each entry in file_hierarchy can be one of:

Sorting

When you use a list and/or glob, multiple files often match. The order in which these files appear is based on two things:

  1. If two files are in the same directory and one file is called "index.*", it will come before the other file.

  2. Otherwise, sorting is alphabetical.

Example 1: All files in a single directory

You can use a single flat glob to collect every file in a directory.

{"file_hierarchy": ["*.md"]}

Example tree:

* index.md
* about.md
* computers.md

Example 2: All files in a directory and its subdirectories

{"file_hierarchy": ["**/*.md"]}

Note: this will not create subsections based on directories. Each document's headings will be at the top level.

Example tree:

* index.md
* about.md
* computers.md
* examples/example_1.md
* examples/example_2.md

Example 3: Explicit ordering with nesting

{
  "file_hierarchy": [
    "Readme.md",
    "Guide.md",
    {"Examples.md": ["examples/*.md"]}
  ]
}

Example tree:

* Readme.md
* Guide.md
* Examples.md
  * examples/example_1.md
  * examples/example_2.md