Installation
To get started, fork and clone the DocStatic repository.
git clone https://github.com/aowendev/docstatic.git
Prerequisites
It is possible to use DocStatic locally or configure your own hosted deployment. However, for the easiest cloud deployment, you may want to sign up for accounts with:
Requirements
For local development, you should install an IDE. Two free open-source options are:
DocStatic consists of a set of Node.js packages. You will need version 18.0 or above (which can be checked by running node -v). You can use nvm to manage multiple Node.js versions on a single machine. When installing Node.js, you should select all checkboxes related to dependencies.
Yarn is used for package management. The Yarn maintainers recommend installing Yarn globally by using the NPM package manager, which is included by default with all Node.js installations. Use the -g flag with npm install to do this:
sudo npm install -g yarn
Then go to the root of the docstatic/ folder and install the dependencies:
yarn install
Project structure
After cloning the repository, you will see these files in the docstatic/ folder:
docstatic
├── apis
│ └── petstore.yaml
├── blog
│ └── hybrid.mdx
├── config
│ ├── docusaurus
│ │ └── index.json
│ ├── homepage
│ │ └── index.json
│ ├── sidebar
│ │ └── index.json
│ └── code-files.json
├── docs
│ └── introduction.mdx
├── i18n
│ └── fr
├── reuse
│ ├── code
│ │ └── example.xml
│ ├── conditions
│ │ └── index.js
│ ├── glossaryTerms
│ │ └── index.js
│ ├── snippets
│ │ └── example.mdx
│ ├── taxonomy
│ │ └── index.json
│ ├── variableSets
│ │ └── index.json
│ └── code-files.json
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── example-page.mdx
│ ├── index.js
│ └── index.module.css
├── static
│ └── img
├── docusaurus.config.ts
├── package.json
├── README.md
├── sidebars.ts
└── yarn.lock
This isn't the complete list, but these are the main ones to be aware of.
Project structure rundown
/apis/- OpenAPI YAML files./blog/- Blog MDX files./config/- JSON files used by TinaCMS to configure DocStatic./docs/- Docs MDX files./i18n/- Translation files./reuse/- Reusable content./src/- Non-documentation files like pages or custom React components./src/pages- Any JSX/TSX/MDX file within this directory are converted into a website page.
/static/- Static folder. Any contents inside here is copied into the root of the final build folder./docusaurus.config.ts- A config file containing the site configuration./package.json- A DocStatic website is a React app. You can install and use any npm packages you want./sidebars.ts- Specifies the order of documents in the sidebar.
Monorepos
If you are using DocStatic for documentation of an existing project, a monorepo may be the solution for you. For more information, refer to Monorepos in the Docusaurus documentation.
Running the development server
To preview your changes as you edit the files, you can run a local development server that will serve your website and reflect the latest changes.
yarn dev
By default, a browser window will open at http://localhost:3000.
Build
DocStatic uses a static site generator to build the website into a folder of static contents and put it on a web server where it can be viewed. To build the website:
yarn build-local
and contents are generated within the /build folder, which can be copied to any static file hosting service such as GitHub pages, Netlify or Vercel. For more information, refer to Deployment in the Docusaurus documentation.