@dataset.sh/doc3 v0.0.4
DocDocDoc
A file-based headless content management library. suitable for managing documentation site and blog.
API
import {Doc3} from "@dataset.sh/doc3"
const doc3 = Doc3('./')
doc3
Folder structure
doc3
manage content entirely based on
- Folder
- sidebar.yaml (optional)
- article1.md
- article2.mdx
- 2023-06-06-article3.mdx (article with date prefix)
- sub-folder
- article1.md
- article2.mdx
- 2023-06-06-article3.mdx (article with date prefix)
Article
This package use gray-matter
to extract metadata from each md
or mdx
files.
Metadata
The following metadata fields are required, and will be automatically generated if missing from front matter.
- title: Title of the article, must be provided.
- slug: slug of the article, the package will first try to read from front matter then filename.
- date: Date of the article, the package will first try to read from front matter, and then filename
pattern
yyyy-mm-dd-slug.md
, thenmodifiedAt
. - modifiedAt: When is this article modified, the package will first try to read from front matter, then
from
fs.stat
.
The following metadata fields will be generated, but can be disabled by certain flags.
- readingTime: Will be calculated based on estimated token count.
sidebar.yaml
You can define a sidebar layout in this file, which is normally used in documentation sites. For example:
---
- title: Intro
slug: intro
- title: Tutorial
slug: tutorial
- title: Advance
slug: advance
children:
- title: Engine
slug: advance/engine
- title: Control
slug: control
The slug fields of children elements don't have to share url prefix of its parent,
for example, if parent node has slug advance
, one of its children can have the url advance/engine
, and another
can have not-advance/some-doc
.
This yaml file should contain ContentNode[]
as defined below.
type ContentNode = {
name: string,
slug?: string,
children?: ContentNode[]
}
Advance Pattern
With doc3, you can easily implement i18n, multiple versioning, and multiple software in one site.
doc3
offers great flexibility and should work for you no matter what i18n, versioning systems you are using.
The easiest way to achieve features such as i18n is to store different version of your content in different folders and
load the
corresponding folder when needed. In that way, doc3
should be flexible enough to work with any i18n setups.
I18N
let locale = 'fr'
const doc3 = Doc3(`locale/${locale}`)
Versioning
let version = '1.0.0'
const doc3 = Doc3(`version/${version}`)
Multiple Software Documentation in One Site
let libname = '...'
const doc3 = Doc3(`lib/${libname}`)
CLI
We also include a cli app, which can be useful for debugging your content folder.
npx doc3 -h
npx doc3 list ./ # list documents
npx doc3 list ./ -t [tag] # list documents by tag
npx doc3 list-tags ./ # list tags
npx doc3 print ./ [slug] # get article for slug
npx doc3 print ./ [slug] -m # get article for slug, but only print metadata
npx doc3 print ./ [slug] -c # get article for slug, but only print content