@dataset.sh/doc3

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, then modifiedAt.
• 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