Lion Logo Lion Guides Components Docs Blog Toggle darkmode

Publish Docs: Overview

A tool that copies and processes your documentation (in a monorepo) so it can be published/shipped with your package.

It will:

  • copy files into your npm package (which is especially useful for mono repositories)
  • processes all markdown files by replacing all relative links to full absolute urls to the commit sha on GitHub
  • have a document structure that is useable on GitHub


For a Mono Repository

  1. Add dependency

    npm i -D publish-docs
  2. Add to your packages/[my-package]/package.json:

    "scripts": {
       "prepublishOnly": "publish-docs --github-url --git-root-dir ../../"
  3. Replace you packages/[my-package]/ with

    # My Pkg
    [=> See Source <=](../../docs/deep/dir/

CLI flags

github-urlstringDefines which GitHub Urls should be generated for relative links (mandatory)
project-dirstringThe directory of your project/package. Defaults to the current working directory
git-root-dirstringThe directory of your git entry point. Defaults to the current working directory
copy-dirstringAllows to copies the content of a folder into the copy-target (relative to the git-root-dir)
copy-targetstringCopies all files into the target (e.g. flattening the directory structure)


cd packages/my-pkg/
publish-docs --github-url --git-root-dir ../../
publish-docs --github-url --git-root-dir ../../ --copy-dir docs/my-components/assets

More Files

Often it makes sense to have multiple documentation files. If you want to bring them along you can do so by adding more [=> See Source <=] hooks.

Bring the in a docs folder along.

👉 packages/[my-package]/docs/

[=> See Source <=](../../docs/deep/dir/

Add a

👉 packages/[my-package]/docs/

[=> See Source <=](../../docs/deep/dir/

So you will end up with something like this in your package.

├── docs
│   ├──
│   └──
├── src
│   ├── my-code.js
│   └── ...
├── package.json

Each of those md files will have a followable link on GitHub and will be replaced with the actual documentation before you publish it.

Copying assets

On top of markdown documentation, there is often the need to bring along accompanying assets.

For that, a copy dir can be provided.

Note: This pattern is relative to the git-root-dir

Therefore given the following tree

├── docs
│   ├── green
│   │   ├── green-data.json
│   │   └──
│   └── red
│       ├── assets
│       │   ├── more
│       │   │   └── red-data.json
│       │   └── red-data.json
│       └──
└── packages
   └── my-pkg       <-- executed here
         ├── docs
         │   └──

we can copy the red assets folder by providing the following copy-dir

"prepublish": "publish-docs --github-url --git-root-dir ../../ --copy-dir docs/red/assets"

The published package will look like this

├── docs
│   ├── assets
│   │   ├── more
│   │   │   └── red-data.json
│   │   └── red-data.json
│   └──