@factorial/docs

Factorial Docs

Factorial Docs lets you quickly create a static documentation site based on Markdown files in your project.

• Installation
• Options
• Creating the homepage
• Specifying the menu
• Adding a meta description
• Usage
• Sitemap

Installation

npm i @factorial/docs

or

yarn add @factorial/docs

Then create a .eleventy.js (or any name of your choice) with the following content:

const config = require("@factorial/docs/config");

module.exports = function (eleventyConfig) {
    return config(eleventyConfig, {
        … // options (see below)
    });
};

Options

All options are optional.

• projectName: string (default: "Factorial")
  The name of the project, e.g. "phabalicious"
• githubUrl: string|null (default: null)
  The URL the of the public repository, e.g. "https://github.com/factorial-io/phabalicious"
• heroImage: object
  • src: string
  • width: number
  • height: number
• logo: object
  • src: string (default: "https://logo.factorial.io/color.png")
  • width: number (default: 30)
  • height: number (default: 42)
• twitter: string
  
• input: string (default: ".")
  The directory in which you markdown files and assets are located
• output: string (default: "build")
  The directory where eleventy writes the build files to
• openSource: boolean (default: false)
  Defines if this project is an open source project or not
• algolia: object
  Configuration object for the algolia search (Keys: appId, apiKey, indexName)
• menu: array (default: null)
  An array to specifiy the menu entries (see Specifying the menu)

Creating the homepage

In your input directory, please create an index.md with the following content:

---
homepage: true
hero_text:
tagline:
action_text:
action_link:
features:
  - title:
    details:
    icon:
footer:
---

Specifying the menu

By default the entries in the menu are in no peticular order. If you want to control the order or hide certain menu entries, you can define an array like the following:

[
  {
    path: "documentation",
    children: ["guide", "installation", "usage"],
  },
  {
    path: "blog",
    children: ["introduction", "architecture"],
  },
  "changelog",
];

Ideally the folder structure reflects the menu structure. That means, for the example above, the folder structure would look like this:

├─ documentation/
│  ├─ README.md / index.md
│  ├─ guide.md
│  ├─ installation.md
│  ├─ usage.md
├─ blog/
│  ├─ README.md / index.md
|  ├─ introduction.md
|  ├─ architecture.md
├─ changelog.md

This would create URLs like the following:

• documentation/
• documentation/guide.html
• documentation/installation.html
• documentation/usage.html
• blog/
• blog/introduction.html
• blog/architecture.html
• changelog.html

If you prefer to have for example documentation.html instead of documentation/, you could also create a documentation.md in the root directory instead of a README.md or index.md inside documentation/.

If you do not want to move the files into a directory, but keep the structure in the menu, you could create the files like this:

├─ documentation.md
├─ guide.md
├─ installation.md
├─ usage.md

In this case, you need to add parent to the front matter of a page:

---
parent: documentation
---

This would create URLs like the following:

• documentation.html
• guide.html
• installation.html
• usage.html

Adding a meta description

To add a meta description, you can use the front matter of a page:

---
meta_description: …
---

Usage

HOST is hostname of the docs, for example "https://docs.phab.io". This is important to generate a correct sitemap.

NOTE: The following example are for yarn users. If you use npm, you need to add a script to your package.json and then use npm run … instead.

Build

FDOCS_HOST=<HOST> yarn fdocs

With individual config name

FDOCS_HOST=<HOST> yarn fdocs --config=.config.js

Development server

FDOCS_HOST=<HOST> yarn fdocs --config=.config.js --serve

With individual config name

FDOCS_HOST=<HOST> yarn fdocs --config=.config.js --serve

Sitemap

A sitemap.xml is automatically created. Please note that when using --serve, it is only created once when the process starts.