doc.mdx

A static site generator on top of Markdown and React

It supports not only Markdown, but also JavaScript and TypeScript.

Basic Usage

Install

$ npm install --save doc.mdx

Configuration

Add a script to your package.json like this:

{
  "scripts": {
    "dev": "doc",
    "build": "doc build"
  }
}

Writing Markdown

Populate ./pages/index.md inside your project:

# Hello World

Development Mode

Just run npm run dev and go to http://localhost:4000.

Production Build

$ npm run build

By default, build output is docs folder.

To change this, run npm run build -o <outdir> or edit package.json.

CLI Usage

Install

$ npm install --global doc.mdx

Create Application

To create <MY-APP>, just run the command below:

$ doc init <MY-APP>

Then, run npm run dev and go to http://localhost:4000

Create Application with Template

You can use examples/* sample apps as templating.

To create the example/with-typescript app, run the command below:

$ doc init <MY-APP> --template with-typescript

CLI Reference

doc init

$ doc init --help

    Description
      Create the doc.mdx application

    Usage
      $ doc init <name> -t <template name>

    <name> represents your application name (default to 'my-app').
    <template name> is listed on examples/* folder.

    Options
      --template, -t  Which example to use as default template
      --help, -h      Displays this message

doc dev (alias of doc)

$ doc dev --help

    Description
      Starts the application in development mode

    Usage
      $ doc dev <dir> -p <port number>

    <dir> represents where the compiled folder should go.
    If no directory is provided, the folder will be created in the current directory.

    Options
      --port, -p      A port number on which to start the application
      --hostname, -H  Hostname on which to start the application
      --help, -h      Displays this message

doc build

$ doc build --help

    Description
      Exports the application for production deployment

    Usage
      $ doc build [options] <dir>

    <dir> represents where the compiled dist folder should go.
    If no directory is provided, the 'docs' folder will be created in the current directory.

    Options
      -o - set the output dir (defaults to 'docs')
      -s - do not print any messages to console
      -h - list this help

Examples

See examples folder for more information.

Or you can start the example app by doc init <app-name> --template <example-dirname>.

Custom Configuration

Doc.mdx is a Next.js wrapper specialized for writing markdown.

So you can customize it using next.config.js.

Develop

Basic

$ git clone https://github.com/saltyshiomix/doc.mdx
$ cd doc.mdx
$ yarn
$ yarn dev # default is examples/hello-world

Developing examples/*

$ yarn dev <EXAMPLE-FOLDER-NAME>