publish-docs v0.2.1
Node Tools >> Publish Docs >> Overview ||10
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
Installation
For a Mono Repository
Add dependency
npm i -D publish-docs
Add to your
packages/[my-package]/package.json
:"scripts": { "prepublishOnly": "publish-docs --github-url https://github.com/ing-bank/lion/ --git-root-dir ../../" }
Replace you
packages/[my-package]/README.md
with# My Pkg [=> See Source <=](https://github.com/ing-bank/lion/blob/83eefe4958d85b149f5b10136d7f51afa33556e7/docs/fundamentals/docs/deep/dir/overview.md)
CLI flags
name | type | description |
---|---|---|
github-url | string | Defines which GitHub Urls should be generated for relative links (mandatory) |
project-dir | string | The directory of your project/package. Defaults to the current working directory |
git-root-dir | string | The directory of your git entry point. Defaults to the current working directory |
copy-dir | string | Allows to copies the content of a folder into the copy-target (relative to the git-root-dir) |
copy-target | string | Copies all files into the target (e.g. flattening the directory structure) |
Examples:
cd packages/my-pkg/
publish-docs --github-url https://github.com/ing-bank/lion/ --git-root-dir ../../
publish-docs --github-url https://github.com/ing-bank/lion/ --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 overview.md
in a docs folder along.
š packages/[my-package]/docs/overview.md
[=> See Source <=](https://github.com/ing-bank/lion/blob/83eefe4958d85b149f5b10136d7f51afa33556e7/docs/fundamentals/docs/deep/dir/overview.md)
Add a use-cases.md
š packages/[my-package]/docs/use-cases.md
[=> See Source <=](https://github.com/ing-bank/lion/blob/83eefe4958d85b149f5b10136d7f51afa33556e7/docs/fundamentals/docs/deep/dir/use-cases.md)
So you will end up with something like this in your package.
.
āāā docs
ā āāā use-cases.md
ā āāā overview.md
āāā src
ā āāā my-code.js
ā āāā ...
āāā package.json
āāā README.md
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
ā ā āāā overview.md
ā āāā red
ā āāā assets
ā ā āāā more
ā ā ā āāā red-data.json
ā ā āāā red-data.json
ā āāā overview.md
āāā packages
āāā my-pkg <-- executed here
āāā docs
ā āāā overview.md
āāā README.md
we can copy the red assets folder by providing the following copy-dir
"prepublish": "publish-docs --github-url https://github.com/ing-bank/lion/ --git-root-dir ../../ --copy-dir docs/red/assets"
The published package will look like this
āāā docs
ā āāā assets
ā ā āāā more
ā ā ā āāā red-data.json
ā ā āāā red-data.json
ā āāā overview.md
āāā README.md