docStatic

A composable documentation solution based on Docusaurus 3 and TinaCMS (including tag management), OpenAPI, Mermaid charts, Lunr search integration and Raw Loader for code snippets.

The project was created by creating a new Docusaurus v3 site with Palo Alto Networks' OpenAPI plugin and merging Tinasaurus to create a working config.

Note: Lunr search is available only in production.

This demo includes the use of snippets (partials), code snippets and variables (on the Test Page). It includes an example workflow for the Docs collection in Tina:

Draft → In Review → In Translation → Published

It enables you to set the Unlisted flag and a Translation Approved flag from Tina.

Local development

# clone the repository
git clone git@github.com:aowendev/docstatic.git

# cd in the project folder
$ yarn

# Start local dev server
$ yarn dev

This installs dependencies and open the website in your browser.

Visit the CMS at http://localhost:3000/admin to start editing.

Folder structure

├── /apis: OpenAPI schemas
├── /blog: blog articles
├── /docs: user docs
│   └── /wiki: wiki
├── /i18n: translation
├── /reuse: reusable content
│   ├── /code: code snippets
│   ├── /snippets: text snippets
│   └── /taxonomy: taxonomy tags
└── /static: static content
    ├─── /img: images
    └─── /reuse: reusable content
         ├── /glossaryTerms: translatable glossary terms
         └── /variableSets: translatable variable sets

Generating OpenAPI Docs

To generate all OpenAPI docs, run this command from the root folder of your project:

yarn gen-api-docs all

This generates API docs for all of the OpenAPI specification (OAS) files referenced in your docusaurus-plugin-openapi-docs config.

You can also generate OpenAPI docs for a single path or OAS by specifying the unique id:

yarn gen-api-docs <id>

Example:

yarn gen-api-docs petstore

This only generates API docs relative to petstore.

If you have multiple versions of the same API, gen-api-docs only generates the latest. To generate all versions, use the --all-versions flag.

Example:

yarn gen-api-docs all --all-versions

This generates API docs for all versions of all the OpenAPI specification (OAS) files referenced in your docusaurus-plugin-openapi-docs config.

Cleaning API Docs

To clean/remove all API Docs, run this command from the root folder of your project:

yarn clean-api-docs all

You can also remove a particular set of API docs by specifying the unique id of your desired spec instance.

yarn clean-api-docs <id>

Example:

yarn clean-api-docs petstore

This removes all API docs relative to burgers.

If you have multiple versions of the same API, clean-api-docs only cleans the latest. To clean all versions, use the --all-versions flag.

Example:

yarn clean-api-docs all --all-versions

This cleans API docs for all versions of all the OpenAPI specification (OAS) files referenced in your docusaurus-plugin-openapi-docs config.

Versioning OpenAPI docs

To generate all versioned OpenAPI docs, run this command from the root folder of your project:

yarn gen-api-docs:version <id>:all

Example:

yarn gen-api-docs:version petstore:all

This generates API docs for all of the OpenAPI specification (OAS) files referenced in your versions config and also generates a versions.json file.

Substitue all with a specific version ID to generate/clean a specific version. Generating for all or a specific version ID automatically updates the versions.json file.

Build

$ yarn build

This command generates static content into the build folder and can be served using any static contents hosting service. For example:

npm run serve

Deployment

To deploy to production and support editing on your live website (at your-company.github.io/baseurl/admin), follow the steps from TinaCMS to deploy to GitHub pages.