From a5977ad66623684fa166c4ac07eb3d300853c09e Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 19 Sep 2023 05:32:28 -0700 Subject: [PATCH] docs: how to embed a file in docs (#2095) Signed-off-by: Meg McRoberts Co-authored-by: Florian Bacher --- .../docs/contrib-guidelines-docs/_index.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/content/en/contribute/docs/contrib-guidelines-docs/_index.md b/docs/content/en/contribute/docs/contrib-guidelines-docs/_index.md index 2ff534451b..c4ca2e0d0b 100644 --- a/docs/content/en/contribute/docs/contrib-guidelines-docs/_index.md +++ b/docs/content/en/contribute/docs/contrib-guidelines-docs/_index.md @@ -32,7 +32,7 @@ that are relevant only to documentation * Avoid using FAQ's in documentation. In general, they say "here is some miscellaneous information that I was too lazy to organize logically for you." - In rare occasions, they may be appropriate, + On rare occasions, they may be appropriate, such as if you need a quick reference to a large, complicated document and include links to detailed documentation about the topic. @@ -50,6 +50,21 @@ that are relevant only to documentation * The Getting Started Guide also includes this information for the same reason. +* When you want to display a sample file that exists in the repository, + use the `embed path` shortcode syntax + (which automatically pulls the current version of the file into your document) + rather than copying the text. + This ensures that, when the sample file is updated, + your document is also updated. + + For example, to embed the `examples/sample-app/version3/app-pre-deploy-eval.yaml` file, + the syntax is: + + ```md + {{}} + + ``` + * `markdownlint` enforces limits on line length. Links to other documents are exempted from this limit but, if a line has words before and after the long string,