You might have internal or classified parts in your documentation that you don’t want to publish. For this reason, you can tag resources, methods, pages and parts of a page or description as private.
When compiling the documentation, you can indicate if you wish to include private blocks as well. If you do so, it will be included and marked as such with a small “lock” icon. This allows you to maintain all your documentation in a single set of source files while being able to produce multiple builds for public and internal usage.
When compiling the documentation, the options are:
# build the public site (remove private content) > grunt dev # build the private site > grunt dev --private=true
Private content can be added at different levels:
To make a whole page private, add
private: true to the front-matter of the
--- title: My Private Page private: true --- Private content here...
When building the private site, a little “lock” icon shows up besides the menu pointing to that page and it will be completely discarded for the public site.
To add some private content within a public page, just enclose your content
<private> tags as follows:
Some public content here <private> Some private content here ... You can also use **Markdown** here. </private> Moving along...
This will generate a private frame inlined in your documentation (and will not appear in the public documentation nor in the source code of the page).
<private>element needs to be at the beginning of a new line in order to be correctly recognized. This behavior makes it possible re-use it in a different context without being scraped (like in this documentation)
<private>element in the markdown file of the RAML documentation (to add private notes to resources descriptions)
For the static content, the metalsmith-scoping plugin is used. Check out the documentation if you want to customize the way private blocks are rendered.