@lion/ui

--- parts: - Overview - Publish Docs - Node Tools title: 'Publish Docs: Overview' eleventyNavigation: key: Node Tools >> Publish Docs >> Overview title: Overview order: 10 parent: Node Tools >> Publish Docs --- # 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 1. Add dependency ```bash npm i -D publish-docs ``` 2. Add to your `packages/[my-package]/package.json`: ```js "scripts": { "prepublishOnly": "publish-docs --github-url https://github.com/ing-bank/lion/ --git-root-dir ../../" } ``` 3. Replace you `packages/[my-package]/README.md` with ```md # My Pkg [=> See Source <=](https://github.com/ing-bank/lion/blob/5f1d7166273cc724458c0239822cd454e16253fa/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` ```md [=> See Source <=](https://github.com/ing-bank/lion/blob/5f1d7166273cc724458c0239822cd454e16253fa/docs/fundamentals/docs/deep/dir/overview.md) ``` Add a `use-cases.md` 👉 `packages/[my-package]/docs/use-cases.md` ```md [=> See Source <=](https://github.com/ing-bank/lion/blob/5f1d7166273cc724458c0239822cd454e16253fa/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 ```js "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 ```