MDocs

This library provides a CLI for generating a documentation website from markdown files. It is using Astro Starlight under the hood, which provides a beautiful UI and a nice user experience.

Mostly everything supported by Astro Starlight is supported by this CLI. This library has a Astro Starlight template in which copies every markdown file of the working directory into the default content/docs collection folder, then executes the build of the project using the configuration file .mdocs.mjs of the working directory and copies the result to the desired destination folder.

The goal of this library is having a CLI with the minimum configuration to generate documentation with a nice UI and UX without effort. There are a lot of flexible and powerful tools for more complex requirements.

Setup

Install the library using your preferred package manager:

npm i -g @astro-tools/mdocs

The library could be installed local to the project if needed.

After installing, the command mdocs should be available in your terminal.

Use

The configuration related to the @astro-tools/mdocs and Astro Starlight must be defined in the working directory file .mdocs.mjs.

Alternatively, the CLI could receive an argument --config with the config file path.

The minimum config file is as follows:

export default {
  starlight: {
    title: 'My Docs',
  }
}

Then execute the command mdocs in the working directory with the previous file:

mdocs

The output should be similar to the following:

[INFO] Copying template...
[INFO] Copying documentation files...
[INFO] Building docs...
<Astro Starlight logs>
[INFO] Copying result into the destination folder...
[INFO] Removing temporal files...
[INFO] Documentation generated successfully!

Transformers

This library uses transformers for modifying the input files before using it. Transformations are being executed in a pipe, using the output of the previous transformation. New files will be added to the transformation pipe from the start.

There are several default transformers but any custom transformer can be added through the .mdocs.mjs file. The default transformers should be enough for most of the projects.

The default transformers are being executed in this order:

1. md-to-mdx
2. readme-to-index
3. local-assets

Each default transformer has a TransformId that can be used to reference it in the transformers option (see below).

md-to-mdx

This transformer removes the level 1 heading (eg. # Title) and adds its content to the MDX attribute title. The transformer ID is md-to-mdx and it has no options.

readme-to-index

This transformer replace root filename README to index and renames every README or index file to its parent folder name.

The transformer ID is readme-to-index and the options are the following:

interface ReadmeToIndexTransformerOptions {
  flat?: boolean;
}

flat?: boolean

Removes the parent folder when there is one, renaming the markdown file to the parent folder name. To disable it, set it to false. Defaults to true.

local-assets

This transformer processes any local image assets (relative path) of any markdown file content including it in the output website. The transformer ID is local-assets and it has no options.

path-mapping

This transformer modifies the output path of any markdown file following the regex rules, cleaning up the website and sidebar tree of undersired routes.

It is not included by default. The transformer ID is path-mapping and the options are the following:

type PathMappingTransformerOptions = {
  mappings: PathMappingTransformerMapping[];
};

mappings: PathMappingTransformerMapping[]

List of mappings to use for transforming the files. Every mapping will be executed over each file, in the declaration order. The type of the mapping is as follows:

interface PathMappingTransformerMapping {
  from: string | RegExp;
  to: string;
};

For example, for removing the src folder from the input file ./packages/my-package/src/sub-library/index.mdx, use:

export default {
  transformers: [
    'md-to-mdx',
    'readme-to-index',
    {
      id: 'path-mapping',
      options: {
        mappings: [{ from: /(\/?)src\//, to: '$1' }],
      },
    },
    'local-assets',
  ],
}

Note

The replacement will use the relative path of the file from the temporal content directory, which initially is the execution working directory.

Options

The libraries tries to minimize the configuration required to build the documentation. In any case, there are some options that can be used for your needs.

pattern

Glob patterns to filter the documentation files to include and copy into the Astro Starlight content/docs directory.

The default value is ['!**/node_modules/', `**/[^_]*.{${extensions.join(',')}}`], being extensions one of markdown, mdown, mkdn, mkd, mdwn, md, mdx.

assets

Assets to be copied into the Astro assets directories. it has the following options:

export default {
  assets: {
    // The content of the folder will be copied into
    // the /public directory of Astro Starlight temporal project
    public: './docs/assets'
  }
}

For example, with the assets.public option, the default favicon.svg can be overriden.

transformers

Functions of type (file: ProcessedFile, context: Context) => Promise<ProcessedFile[] | ProcessedFile> that transform the input file, allowing to modify the output path (including the file name) and the content (if available).

The ProcessedFile type is:

interface ProcessedFile {
  input: string;
  output: string;
  content?: string;
}

The Context type is:

interface Context {
  executionDir: string; // absolute path to the root of the temporal project folder
  contentDir: string; // relative to the executionDir
  assetsDir: string; // relative to the executionDir
}

When returning an array, the first position must be the result of transforming the incoming file. Following files will be added to the processing queue from the start.

Caution

Adding custom transfomers will remove the default transfomers from the transform pipe. You have to include them explicity as in the example below.

To include any default transformer, reference it by TransformId in the transfomers option. This way allows to use the transformer without explicitly importing it. For example:

export default {
  transfomers: [
    (file, context) => { /* your custom logic */ },
    'md-to-mdx',
    {
      id: 'path-mapping',
      options: {
        mappings: [
          { from: /(\/?)src\//, to: '$1' },
        ],
      },
    }
  ]
}

The declaration order will be the execution order.

For using the default transformers in your custom transformers, just import them from @astro-tools/mdocs using the getTransformer(id: TransformerId | TransformerDefinition): Transformer function:

export default function (file, context) {
  const mdToMdxTransformer = getTransformer('md-to-mdx');

  // your custom logic

  return mdToMdxTransformer(file, context);
}

starlight

The configuration that is going to be used for the Astro Starlight integration. The required properties can be checked in the Astro Starlight configuration reference page.

Currently, only the title property is required.