Skeleton documentation generator for Docusaurus v2 and v1
npm install skelosaurusv2!npm !npm bundle size (version) !npm !GitHub last commit !GitHub !Built with Docusaurus v2
!Outlined with Skelosaurus v2
skelo -h
skelo help build
skelo help load
skelo help save
Overview pages automatically
bash
npm i skelosaurusv2 -g
`
The skelo command now available at the command prompt.
Usage
$3
See commands and general options.
`txt
Usage: skelo [options] outlineFiles...Skeleton documentation generator for Docusaurus (v2 and v2)
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
build [options] build doc files and sidebars file
load [options] load documentation parts into respective
files
save [options] save documentation parts into respective
files
help [command] display help for command
`
> build is the default command, so you can provide its arguments and options without including the build command.
$3
See arguments and options for build command.
`txt
Usage: skelo build [options]
build doc files and sidebars file
Options:
-c, --clear start with a clear docs path
-d, --docs path where markdown files are generated into (default:
"./docs")
-f, --autofolder create subfolder for categories and subtopics (default:
false)
-i, --intro create in Intro page in each subcategory
--introTitle [title] title to use in intro pages (default: "Overview")
--no-v2 generate for Docusaurus v1
-o, --out filename to contains sidebars (default: "sidebars")
-p, --parts [path] path where parts will be stored (default: "./")
-w, --website path to store sidebars content file (default: "./")
-h, --help display help for command
`
$3
See arguments and options for load command.
`txt
Usage: skelo load [options]load documentation parts into respective files
Options:
-d, --docs path where markdown files are generated into (default:
"./docs")
-w, --website path to store sidebars content file (default: "./")
-h, --help display help for command
`
$3
See arguments and options for save command.
`txt
Usage: skelo save [options]save documentation parts into respective files
Options:
-d, --docs path where markdown files are generated into (default:
"./docs")
-w, --website path to store sidebars content file (default: "./")
-h, --help display help for command
`
Quick example
$3
Create a working folder sample and a documentation outline file sample.md which contains documention outline as Markdown.
`bash
mkdir sample
cd sample
echo Documentation outline for Docusaurus > sample.md
`
In sample.md copy the following:
`markdown
An example of using Markdown to design documentation structure for Docusaurus v1 and v2.
docs
- Getting started
- Introduction
- Building
- Generating
- Allowing new features
- Delegating responsabilities
- Controversies
- Guides
- How to create new features
- API
- CLI commands
- sidebars.js
tutorials
- Tutorial
- Creating simple files
- Adding content and subtopics
- Create folders from titles
`
Install Docusaurus in your working folder.
`bash
npx @docusaurus/init@next init sample-doc classic
`
This will create the sample-doc documentation project as inside your working folder.
$3
Generate skeleton documentation with skelo:
`bash
skelo build sample -w ./sample-doc -d ./sample-doc/docs
`
The sample\sample-doc\docs folder contains .md topic source files for your documentation. The sample\sample-doc\sidebars.js contains the navigation description.
`txt
sample-doc
├── docs
│ ├── installation.md
│ └── other-topic.md
└── sidebars.js
`
The sample\sample-doc\sidebars.js exports the sidebar navigation design.
`javascript
/**
* Sidebar definitions for Docusaurus v2
*/
module.exports = {
"docs": {
"Getting started": [
"introduction",
"building",
{
"type": "category",
"label": "Generating",
"items": [
"allowing-new-features",
"delegating-responsabilities"
]
},
"controversies"
],
"Guides": [
"how-to-create-new-features"
],
"API": [
"cli-commands",
"sidebars-js"
]
},
"tutorials": {
"Tutorial": [
"creating-simple-files",
"adding-content-and-subtopics",
"create-folders-from-titles"
]
}
}
`
The sample\sample-doc\docs\introduction.md has the front-matter Docusaurus expects, and is already filled with a lorem ipsum text.
`markdown
---
title: Introduction
id: introduction
sidebar_label: Introduction
---
Irure est eiusmod pariatur mollit exercitation sunt occaecat consectetur. Id nisi minim eu elit sint esse magna eiusmod commodo consequat ea sunt id amet. Et consectetur ea eiusmod aute sunt mollit est cillum sunt reprehenderit officia non qui commodo. Ad adipisicing adipisicing non cillum exercitation eiusmod est voluptate dolor pariatur nulla cupidatat fugiat. Et non anim nostrud culpa.
`
$3
Open the sample\sample-doc\docusaurus.config.js, and edit the themeConfig:
`javascript
themeConfig: {
navbar: {
title: 'My Site',
logo: {
alt: 'My Site Logo',
src: 'img/logo.svg',
},
items:
{
// to: 'docs/',
to: 'docs/introduction',
activeBasePath: 'docs',
label: 'Docs',
position: 'left',
},
...
`
Now, start Docusaurus local server.
`bash
cd sample-doc
npm run start
`
Docusaurus does its magic and finally opens up the local documentation site it created. Click Docs item in the top navigation menu to see the navigation bar and basic content for each topic.
![Screenshot
Creating documentation folders
$3
To create folders automatically, use the -f or --autofolders switch.
`bash
skelo sample -f -w ./sample-folders-doc -d ./sample-folders-doc/docs
`
> Because build is the default command, you can skip providing the command name explicityly, like in the example above. In the example above, sample is the outline filename. If the extension of the outline file is .md, you can skip writing it.
This will generate the documentation .md files and sidebars.js file as before, but it also creates a subfolder for each topic with items. Here is the folder structure in sample/sample-folders-doc:
`txt
sample-folders-docs
├── docs
│ ├── adding-content-and-subtopics.md
│ ├── allowing-new-features.md
│ ├── building.md
│ ├── cli-commands.md
│ ├── controversies.md
│ ├── create-folders-from-titles.md
│ ├── creating-simple-files.md
│ ├── delegating-responsabilities.md
│ ├── how-to-create-new-features.md
│ ├── introduction.md
│ ├── overview-07669.md
│ ├── overview-46414.md
│ ├── overview-71580.md
│ ├── overview-96116.md
│ ├── overview.md
│ └── sidebars-js.md
├── sidebars.js
└── tree.txt
`
The sample\sample-folders-doc\sidebars.js is also changed to include the file paths.
`javascript
module.exports = {
"docs": {
"Getting started": [
"overview",
"introduction",
"building",
{
"type": "category",
"label": "Generating",
"items": [
"overview",
"allowing-new-features",
"delegating-responsabilities"
]
},
"controversies"
],
"Guides": [
"overview",
"how-to-create-new-features"
],
"API": [
"overview",
"cli-commands",
"sidebars-js"
]
},
"tutorials": {
"Tutorial": [
"overview",
"creating-simple-files",
"adding-content-and-subtopics",
"create-folders-from-titles"
]
}
}
`
$3
When you want to indicate a topic as a folder in which subtopics will go:
1. use the @f marker in your outline file
2. do NOT include the -f (--autofolders) switch in command line.
Creating
Overview pages automatically
Automatically insert an Overview documentation page as the first item in a navigation section or list of subtopics. This will save you time and make your documentation have a consistent look.
To create the Overview pages automatically, use the -i or --intro switch. By default, the title of the overview pages is set to Overview. You can specify a different title for the overview page with the --introTitle option.
`bash
skelo sample -i -f sample -w ./sample-folders-doc -d ./sample-folders-doc
``
Array.ObjectBuild list of topics and subcategories in a category.
ArrayBuild headers as template variables
objectBuild items of navigation section.
stringCreate topic documentation topic in Markdown.
Get document parts in specified file
Create parts files for a specified topic document
objectExtract sidebar title and sidebar outline from a Markdown file.
ArrayBuild topic top headers
stringReturn a variant string
booleanChecks whether the topic has headers
booleanChecks whether a topic has children topics
stringReturn a random string with digital characters of specified length
objectExtract topic title to extract relevant information
Create a text file in utf-8 format from specified name and content
stringConvert specified string into a slug.
Converts spaces, tabs, and visible special characters into dashes (-) -- except backslash ().
Compresses sequence of dashes or special characters into a single dash. Removes heading or trailing
dashes or special characters from the specified string.
Kind: global function
Returns: Array.Object - List of topics and categories.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| bulletList | Array | | The bullet list internal representation. |
| [options] | object | { 'parent': './', 'prefix': '' } | Options for building topic slug and folders |
Kind: global function
Returns: Array - Array of objects where each object is a set of template variables
Opts: object Command line options passed as properties
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| bulletlist | Array | | Representation of list in Markdown abstract tree |
| [level] | number | 2 | Heading level for Markdown notation |
Kind: global function
Returns: object - Key-value where key is category title and value is a list of items or subcategories.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| bulletList | Array | | The bullet list internal representation. |
| [options] | object | { 'parent': './' } | Options for building section slug |
Kind: global function
Returns: string - Topic unique slug
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| title | string | | Topic title |
| [options] | object | { 'headers': [], 'parent': './', 'prefix': '' } | Options for creating topic file. |
Kind: global function
| Param | Type | Description |
| --- | --- | --- |
| sourceFile | string | Path to documentation file @ @returns {Array.{targetPath: string, content: string}} Array of part object, each part has targetPath and content properties |
Kind: global function
| Param | Type | Description |
| --- | --- | --- |
| sourceFile | string | Path to topic document |
| program | object | Options passed on command |
Kind: global function
Returns: object - Key-value where key is the sidebar title and value is bullet list tree.
| Param | Type | Description |
| --- | --- | --- |
| sourceFilename | string | Filename of a Markdown file with outline |
Kind: global function
Returns: Array - Headers in markdown notation
| Param | Type | Description |
| --- | --- | --- |
| bulletlist | Array | Header list represented in Markdown abstrat tree |
| Command | object | line options passed as properties |
Kind: global function
Returns: string - Original string with suffixed text
| Param | Type | Description |
| --- | --- | --- |
| name | string | The name to check for uniqueness |
Kind: global function
Returns: boolean - true if topic has headers, false otherwise.
| Param | Type | Description |
| --- | --- | --- |
| topicItem | object | Topic to test whether it has headers |
Kind: global function
Returns: boolean - true if single topic, false otherwise
| Param | Type | Description |
| --- | --- | --- |
| topicItem | object | Topic to test whether it is single topic |
Kind: global function
Returns: string - Randomly chosen characters of specified length
| Param | Type | Description |
| --- | --- | --- |
| length | number | The length of string to return. |
Kind: global function
Returns: object - Properties extracted from title
| Param | Type | Description |
| --- | --- | --- |
| topicTitle | object | Topic title to parse. |
Kind: global function
| Param | Type | Description |
| --- | --- | --- |
| fileName | string | Name of the file to create. |
| content | string | String to place in the file. |
Kind: global function
Returns: string - Trimmed, lowercase string with dashes(-)
| Param | Type | Description |
| --- | --- | --- |
| source | string | String to covert to slug. |