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
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)
});
};
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 | false-
src
: string (default:"https://logo.factorial.io/color.png"
) -
width
: number (default:30
) -
height
: number (default:42
)
-
-
footerLogo
: object | false (default:logo
)-
src
: string -
width
: number -
height
: number
-
-
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)
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:
---
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
To add a meta description, you can use the front matter of a page:
---
meta_description: …
---
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.
FDOCS_HOST=<HOST> yarn fdocs
FDOCS_HOST=<HOST> yarn fdocs --config=.config.js
FDOCS_HOST=<HOST> yarn fdocs --config=.config.js --serve
FDOCS_HOST=<HOST> yarn fdocs --config=.config.js --serve
A sitemap.xml
is automatically created. Please note that when using --serve
, it is only created once when the process starts.