Getting Started

Installation

Docspire can be used on its own, or be installed into an existing project. In both cases, you start with:

npm install docspire -D

Usage

To build your documentation, you can run:

npx docspire

To rebuild your documentation when you change your source files, you can run:

npx docspire --watch

Lastly, to rebuild your documentation when you change your source files and serve it on a local server, you can run:

npx docspire --serve

Configuration

To customize Docspire, you can create a docspire.config.js file in your project root. There are many configuration options to deeply customize your documentation site and its behavior. You can specify them all in a docspire.config.js or in a docspire.config.json file in your project root. To specify a different configuration file, you can use the -c or --config option:

npx docspire -c _build/docspire.config.js

Branding

The header shows your brand, built from these options:

// docspire.config.js
export default {
	title: "Nudeps",
	icon: "/logo.svg",
	wordmark: "/wordmark.svg",
};
Option What it is Where it shows
title The site name, as text Header (unless wordmark or logo is set), page titles, alt text
title_html The site name, as HTML Header, instead of title
icon An image of the mark alone Header, favicon. Defaults to Docspire’s icon
wordmark An image of the name alone Header, instead of title
logo An image of the mark and name together Header, instead of icon and the name

The header picks the first that applies:

  1. logo
  2. icon + wordmark
  3. icon + title_html
  4. icon + title

To style a text name, target header .logo in your CSS.

Renaming Docspire’s directories

Docspire reads components/ at the project root as the site’s own components. A site that registers itself as a plugin also has its root templates/ and assets/ read.

When one of those names already means something else in your project, rename Docspire’s. A component library, for example, has a components/ of its own, which is not Docspire’s:

// docspire.config.js
export default {
	dirNames: { components: "docspire-components" },
};

Docspire now reads the site’s components from docspire-components/ and leaves components/ alone.

The keys are components, templates and assets, and a name you leave out keeps its default. Renaming the site’s directories never touches a plugin’s: every plugin keeps its own components/, templates/ and assets/. So does a component’s own folder — its sub-components still live in <component>/components/<sub-component>/, e.g. docspire-components/my-card/components/my-card-title/.

Note

This renames where Docspire reads from, not where the library’s own files are published. To serve them, copy them as you would any other file, e.g. with config.addPassthroughCopy() in a plugin.