Basic Usage

Once docmd is installed, using it involves a few simple commands to manage your documentation project.

1. Initialize Your Project (docmd init)

Navigate to the directory where you want to create your documentation project. If the directory doesn’t exist, create it first.

mkdir my-awesome-docs
cd my-awesome-docs

Then, run the init command:

docmd init

This command sets up the basic structure for your docmd project:

  • docs/: An empty directory where your Markdown source files will live.
    • docs/index.md: A sample Markdown file to get you started.
  • config.js: A configuration file for your site, pre-filled with sensible defaults.

You’ll typically edit config.js to set your site title and define the navigation structure, and then start adding your .md files to the docs/ directory.

2. Add and Structure Content

Create your Markdown (.md) files inside the docs/ directory. You can organize them into subdirectories as needed. For example:

my-awesome-docs/
├── docs/
│   ├── index.md
│   └── api/
│       ├── introduction.md
│       └── endpoints.md
│   └── guides/
│       ├── setup.md
│       └── advanced.md
└── config.js

Each Markdown file should start with YAML frontmatter to define metadata like the page title. See Writing Content > Frontmatter for details.

3. Preview Your Site (docmd dev)

While you’re writing content or configuring your site, you’ll want to see a live preview. The dev command starts a local development server with live reloading.

In your project’s root directory (e.g., my-awesome-docs/), run:

docmd dev

This will:

  1. Perform an initial build of your site.
  2. Start a web server, typically at http://localhost:3000.
  3. Watch your docs/ directory and config.js for changes.
  4. Automatically rebuild the site and refresh your browser when changes are detected.

Open http://localhost:3000 in your web browser to see your site. Any changes you save to your Markdown files or config.js will be reflected live in the browser.

To stop the development server, press Ctrl+C in your terminal.

4. Build Your Static Site (docmd build)

When you’re ready to deploy your documentation or create a production version, use the build command:

docmd build

This command:

  1. Reads your config.js.
  2. Processes all .md files in your docs/ directory.
  3. Generates the complete static HTML, CSS, and JavaScript assets.
  4. Outputs the entire site into a site/ directory (by default, configurable in config.js).

The contents of the site/ directory are all you need to deploy your documentation. You can upload this folder to any static web hosting provider. See Deployment for more information.

This covers the fundamental workflow of using docmd. Next, you’ll want to learn more about Writing Content and Configuration.

Previous Installation Next Content