The scenario
Content is being pulled from an external source - for example, the Cloud Native PostgreSQL Operator docs. Upon import, Docs-specific content is being merged into it - for example, live demos.
The problem
Cross-links between external content and Docs-specific content should be exposed upon import, but not rendered in the source repo or other targets (where they will not function). But, ideally these links would be integral to the source material (along with associated supporting content and metadata such as descriptions, YAML, etc) so that their nature and position is not a surprise to authors.
The solution
Create functionality to be used by the import scripts that will process specially-constructed comments and surface them in the imported documents / metadata.
Example:
A source file named mkdocs.yml is used to define the navigation in the source material, and migrated into Frontmatter during the import. YAML comments prefixed with docs-content are used for navigation items that should only be exposed upon import:
nav:
- "a page in the source"
#docs-content - "a page merged during import"
- "different page in the source"
A source file named quickstart.md contains content relevant to the product. HTML comments prefixed with docs-content are used to contain additional content which will direct readers to a live demo that will be merged in during import:
Original paragraph text blah blah blah
<!-- docs-content
!!! Admonition
that should only appear after import
-->
blah blah more original text
(Example inspired by this PR: #1094, which uses a rather more clunky method of merging)
When should this be implemented?
When there exists more than a single page that could make use of it!
The scenario
Content is being pulled from an external source - for example, the Cloud Native PostgreSQL Operator docs. Upon import, Docs-specific content is being merged into it - for example, live demos.
The problem
Cross-links between external content and Docs-specific content should be exposed upon import, but not rendered in the source repo or other targets (where they will not function). But, ideally these links would be integral to the source material (along with associated supporting content and metadata such as descriptions, YAML, etc) so that their nature and position is not a surprise to authors.
The solution
Create functionality to be used by the import scripts that will process specially-constructed comments and surface them in the imported documents / metadata.
Example:
A source file named
mkdocs.ymlis used to define the navigation in the source material, and migrated into Frontmatter during the import. YAML comments prefixed withdocs-contentare used for navigation items that should only be exposed upon import:A source file named
quickstart.mdcontains content relevant to the product. HTML comments prefixed withdocs-contentare used to contain additional content which will direct readers to a live demo that will be merged in during import:(Example inspired by this PR: #1094, which uses a rather more clunky method of merging)
When should this be implemented?
When there exists more than a single page that could make use of it!