https://github.com/ioncakephper/sk2
Generate sidebar file and topic files for Docusaurus-powered documentation site.
https://github.com/ioncakephper/sk2
Last synced: 5 months ago
JSON representation
Generate sidebar file and topic files for Docusaurus-powered documentation site.
- Host: GitHub
- URL: https://github.com/ioncakephper/sk2
- Owner: ioncakephper
- License: mit
- Created: 2023-01-04T12:22:17.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-12-11T14:04:07.000Z (about 1 year ago)
- Last Synced: 2025-01-21T23:33:38.408Z (11 months ago)
- Language: JavaScript
- Homepage:
- Size: 1.42 MB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# sk2
Generate sidebar file and topic files for Docusaurus-powered documentation site.
## Install
To use the `sk2` CLI, you have to install the `sk2` package globally.
```bash
npm i -g sk2
```
Check `sk2` CLI is available:
```bash
sk2 -V # ask sk2 version
1.0.0 # or any other version confirms that sk2 responds
```
## Usage
```bash
sk2 [options] [command]
```
If you specify no command, the `build` command is executed.
```txt
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
build [options] [outline...] generate sidebar and topic files from outline file(s).
help [command] display help for command
```
### Commands
#### `build`
generate sidebar and topic files from outline file(s).
`sk2 build [options] [outline...]`
**`Arguments`**
- **`outline:`** filename(s) with sidebar outlines (default: "sk2-outline")
**`Options`**
- **`-s, --sidebar :`** path and name of sidebar file to generate (default: "./sidebar.js")
- **`-d, --docs :`** path to Docusaurus project docs root folder (default: "./docs")
- **`--outlineExtension :`** outline file default extension (default: ".yaml")
- **`--autoFolder`** create a folder for every category
- **`--autoOverview`** create an overview page for every category
- **`--templatePath :`** path to templates for sidebars, topic, and headings.
- **`--topicExtension :`** topic file extension (default: ".md")
- **`--verbose`** provide progress messages.
## Outline element properties
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `brief` | `string` | null | Short topic description to appear as the first paragraph in topic document. |
| `description` | `string` | null | Description to appear in HTML page description meta tag |
| `folder` | `string` | null | Path of topic relative to `docs` folder in Docusaurus. Separate folders with forward slash `/`. Spaces in a folder are converted to `_`. |
| `headings` | `Array` | `[]` | Headings of current topic. Add subheadings in the items element of a heading item. |
| `id` | `string` | null | Topic identifier to override the one built from label. Spaces in id are converted to `_`. |
| `items` | `Array` | `[]` | Items of current sidebar topic. A topic with non-empty items is a sidebar category |
| `label` | `string` | | Appears in sidebar as topic identifier |
| `slug` | `string` | null | Used as an alternative topic filename. |
| `title` | `string` | null | Appears as topic title instead of topic label. |
## Examples
### Example 1: Use default options and outline filename
```bash
cd my-work-folder
sk2
```
* the `build` command is invoked
* it looks for the `sk2-outline.yaml` in the current folder (my-work=folder)
* generates the `sidebars.js` file in the current folder, and topic files in the `docs` subfolder.
* topic files have the `.md` extension