From 22cb3eeb6df1d36e331002a17d1ffbed23afeb7e Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 13:18:43 +0100 Subject: [PATCH] Cleanup --- content/en/docs/Contribute/_index.md | 6 +- .../Contribute/{style => }/style-guide.md | 63 +- content/en/docs/Contribute/style/_index.md | 7 - .../en/docs/Contribute/style/content-guide.md | 74 -- .../Contribute/style/content-organization.md | 147 ---- .../en/docs/Contribute/style/diagram-guide.md | 780 ------------------ .../style/hugo-shortcodes/example1.md | 9 - .../style/hugo-shortcodes/example2.md | 7 - .../Contribute/style/hugo-shortcodes/index.md | 410 --------- .../style/hugo-shortcodes/podtemplate.json | 22 - .../Contribute/style/page-content-types.md | 218 ----- .../docs/Contribute/style/write-new-topic.md | 170 ---- 12 files changed, 35 insertions(+), 1878 deletions(-) rename content/en/docs/Contribute/{style => }/style-guide.md (90%) delete mode 100644 content/en/docs/Contribute/style/_index.md delete mode 100644 content/en/docs/Contribute/style/content-guide.md delete mode 100644 content/en/docs/Contribute/style/content-organization.md delete mode 100644 content/en/docs/Contribute/style/diagram-guide.md delete mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/example1.md delete mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/example2.md delete mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/index.md delete mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/podtemplate.json delete mode 100644 content/en/docs/Contribute/style/page-content-types.md delete mode 100644 content/en/docs/Contribute/style/write-new-topic.md diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 2924b4410bd4..c03fc9aa3ddc 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -182,7 +182,7 @@ class changes,changes2 white Figure 2. Working from a local fork to make your changes. -#### Fork the kubernetes/website repository +#### Fork the open-telemetry/opentelemetry.io repository 1. Navigate to the [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) repository. 1. Select **Fork**. @@ -447,7 +447,7 @@ create a merge conflict. You must resolve all merge conflicts in your PR. ## Contribute to other repos -The [Kubernetes project](https://github.com/open-telemetry) contains many +The [OpenTelemetry project](https://github.com/open-telemetry) contains many repositories. Many of these repositories contain documentation: user-facing help text, error messages, API references or code comments. @@ -483,7 +483,7 @@ If you have an idea for new content, but you aren't sure where it should go, you can still file an issue. Either: - Choose an existing page in the section you think the content belongs in and click **Create documentation issue**. -- Go to [GitHub](https://github.com/kubernetes/website/issues/new/) and file the issue directly. +- Go to [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) and file the issue directly. ## How to file great issues diff --git a/content/en/docs/Contribute/style/style-guide.md b/content/en/docs/Contribute/style-guide.md similarity index 90% rename from content/en/docs/Contribute/style/style-guide.md rename to content/en/docs/Contribute/style-guide.md index b6a881987902..01a4e22a7e86 100644 --- a/content/en/docs/Contribute/style/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -1,16 +1,17 @@ --- -title: Documentation Style Guide +title: Documentation style guide linktitle: Style guide -content_type: concept weight: 40 +cSpell:ignore: +slug: style-guide --- -This page gives writing style guidelines for the Kubernetes documentation. +This page gives writing style guidelines for the OpenTelemetry documentation. These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. -For additional information on creating new content for the Kubernetes +For additional information on creating new content for the OpenTelemetry documentation, read the [Documentation Content Guide](/docs/contribute/style/content-guide/). Changes to the style guide are made by SIG Docs as a group. To propose a change @@ -20,7 +21,7 @@ SIG Docs meeting, and attend the meeting to participate in the discussion. {{< note >}} -Kubernetes documentation uses +OpenTelemetry documentation uses [Goldmark Markdown Renderer](https://github.com/yuin/goldmark) with some adjustments along with a few [Hugo Shortcodes](/docs/contribute/style/hugo-shortcodes/) to support @@ -29,10 +30,10 @@ glossary entries, tabs, and representing feature state. ## Language -Kubernetes documentation has been translated into multiple languages -(see [Localization READMEs](https://github.com/kubernetes/website/blob/main/README.md#localization-readmemds)). +OpenTelemetry documentation has been translated into multiple languages +(see [Localization READMEs](https://github.com/open-telemetry/opentelemetry.io/blob/main/README.md#localization-readmemds)). -The way of localizing the docs for a different language is described in [Localizing Kubernetes Documentation](/docs/contribute/localization/). +The way of localizing the docs for a different language is described in [Localizing OpenTelemetry Documentation](/docs/contribute/localization/). The English-language documentation uses U.S. English spelling and grammar. @@ -151,9 +152,9 @@ The value of the `exec` field is an ExecAction object. | The value of the "exec" Run the process as a DaemonSet in the `kube-system` namespace. | Run the process as a DaemonSet in the kube-system namespace. {{< /table >}} -### Use code style for Kubernetes command tool and component names +### Use code style for OpenTelemetry command tool and component names -{{< table caption = "Do and Don't - Use code style for Kubernetes command tool and component names" >}} +{{< table caption = "Do and Don't - Use code style for OpenTelemetry command tool and component names" >}} Do | Don't :--| :----- The kubelet preserves node stability. | The `kubelet` preserves node stability. @@ -167,7 +168,7 @@ Run the process with the certificate, `kube-apiserver --client-ca-file=FILENAME` Do | Don't :--| :----- The `kubeadm` tool bootstraps and provisions machines in a cluster. | `kubeadm` tool bootstraps and provisions machines in a cluster. -The kube-scheduler is the default scheduler for Kubernetes. | kube-scheduler is the default scheduler for Kubernetes. +The kube-scheduler is the default scheduler for OpenTelemetry. | kube-scheduler is the default scheduler for OpenTelemetry. {{< /table >}} ### Use a general descriptor over a component name @@ -175,7 +176,7 @@ The kube-scheduler is the default scheduler for Kubernetes. | kube-scheduler is {{< table caption = "Do and Don't - Use a general descriptor over a component name" >}} Do | Don't :--| :----- -The Kubernetes API server offers an OpenAPI spec. | The apiserver offers an OpenAPI spec. +The OpenTelemetry API server offers an OpenAPI spec. | The apiserver offers an OpenAPI spec. Aggregated APIs are subordinate API servers. | Aggregated APIs are subordinate APIServers. {{< /table >}} @@ -191,25 +192,25 @@ Set the value of `image` to nginx:1.16. | Set the value of `image` to `nginx:1.1 Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`. {{< /table >}} -## Referring to Kubernetes API resources +## Referring to OpenTelemetry API resources This section talks about how we reference API resources in the documentation. ### Clarification about "resource" -Kubernetes uses the word "resource" to refer to API resources, such as `pod`, +OpenTelemetry uses the word "resource" to refer to API resources, such as `pod`, `deployment`, and so on. We also use "resource" to talk about CPU and memory requests and limits. Always refer to API resources as "API resources" to avoid confusion with CPU and memory resources. -### When to use Kubernetes API terminologies +### When to use OpenTelemetry API terminologies -The different Kubernetes API terminologies are: +The different OpenTelemetry API terminologies are: - Resource type: the name used in the API URL (such as `pods`, `namespaces`) - Resource: a single instance of a resource type (such as `pod`, `secret`) - Object: a resource that serves as a "record of intent". An object is a desired - state for a specific part of your cluster, which the Kubernetes control plane tries to maintain. + state for a specific part of your cluster, which the OpenTelemetry control plane tries to maintain. Always use "resource" or "object" when referring to an API resource in docs. For example, use "a `Secret` object" over just "a `Secret`". @@ -227,8 +228,8 @@ For more information about PascalCase and code formatting, please review the rel [Use upper camel case for API objects](/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects) and [Use code style for inline code, commands, and API objects](/docs/contribute/style/style-guide/#code-style-inline-code). -For more information about Kubernetes API terminologies, please review the related -guidance on [Kubernetes API terminology](/docs/reference/using-api/api-concepts/#standard-api-terminology). +For more information about OpenTelemetry API terminologies, please review the related +guidance on [OpenTelemetry API terminology](/docs/reference/using-api/api-concepts/#standard-api-terminology). ## Code snippet formatting @@ -255,24 +256,24 @@ NAME READY STATUS RESTARTS AGE IP NODE nginx 1/1 Running 0 13s 10.200.0.4 worker0 ``` -### Versioning Kubernetes examples +### Versioning OpenTelemetry examples Code examples and configuration examples that include version information should be consistent with the accompanying text. -If the information is version specific, the Kubernetes version needs to be defined +If the information is version specific, the OpenTelemetry version needs to be defined in the `prerequisites` section of the [Task template](/docs/contribute/style/page-content-types/#task) or the [Tutorial template](/docs/contribute/style/page-content-types/#tutorial). Once the page is saved, the `prerequisites` section is shown as **Before you begin**. -To specify the Kubernetes version for a task or tutorial page, include +To specify the OpenTelemetry version for a task or tutorial page, include `min-kubernetes-server-version` in the front matter of the page. If the example YAML is in a standalone file, find and review the topics that include it as a reference. Verify that any topics using the standalone YAML have the appropriate version information defined. If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it. -For example, if you are writing a tutorial that is relevant to Kubernetes version 1.8, +For example, if you are writing a tutorial that is relevant to OpenTelemetry version 1.8, the front-matter of your markdown file should look something like: ```yaml @@ -291,14 +292,14 @@ kind: Pod ... ``` -## Kubernetes.io word list +## OpenTelemetry.io word list -A list of Kubernetes-specific terms and words to be used consistently across the site. +A list of OpenTelemetry-specific terms and words to be used consistently across the site. -{{< table caption = "Kubernetes.io word list" >}} +{{< table caption = "OpenTelemetry.io word list" >}} Term | Usage :--- | :---- -Kubernetes | Kubernetes should always be capitalized. +OpenTelemetry | OpenTelemetry should always be capitalized. Docker | Docker should always be capitalized. SIG Docs | SIG Docs rather than SIG-DOCS or other variations. On-premises | On-premises or On-prem rather than On-premise or other variations. @@ -481,7 +482,7 @@ Update the title in the front matter of the page or blog post. | Use first level Use ordered headings to provide a meaningful high-level outline of your content. | Use headings level 4 through 6, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles. Use pound or hash signs (`#`) for non-blog post content. | Use underlines (`---` or `===`) to designate first-level headings. Use sentence case for headings in the page body. For example, **Extend kubectl with plugins** | Use title case for headings in the page body. For example, **Extend Kubectl With Plugins** -Use title case for the page title in the front matter. For example, `title: Kubernetes API Server Bypass Risks` | Use sentence case for page titles in the front matter. For example, don't use `title: Kubernetes API server bypass risks` +Use title case for the page title in the front matter. For example, `title: OpenTelemetry API Server Bypass Risks` | Use sentence case for page titles in the front matter. For example, don't use `title: OpenTelemetry API server bypass risks` {{< /table >}} ### Paragraphs @@ -610,7 +611,7 @@ whether they're part of the "we" you're describing. Do | Don't :--| :----- Version 1.4 includes ... | In version 1.4, we have added ... -Kubernetes provides a new feature for ... | We provide a new feature ... +OpenTelemetry provides a new feature for ... | We provide a new feature ... This page teaches you how to use pods. | In this page, we are going to learn about pods. {{< /table >}} @@ -661,10 +662,10 @@ These steps ... | These simple steps ... {{< /table >}} ### EditorConfig file -The Kubernetes project maintains an EditorConfig file that sets common style preferences in text editors +The OpenTelemetry project maintains an EditorConfig file that sets common style preferences in text editors such as VS Code. You can use this file if you want to ensure that your contributions are consistent with the rest of the project. To view the file, refer to -[`.editorconfig`](https://github.com/kubernetes/website/blob/main/.editorconfig) in the repository root. +[`.editorconfig`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.editorconfig) in the repository root. ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/Contribute/style/_index.md b/content/en/docs/Contribute/style/_index.md deleted file mode 100644 index d3633b5aaae5..000000000000 --- a/content/en/docs/Contribute/style/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Style guide -description: The OpenTelemetry Documentation Style Guide helps you contribute better docs, faster. -weight: 80 ---- - -The OpenTelemetry Documentation Style Guide describes writing, formatting, and editing standards that apply to OpenTelemetry documentation. The style guide helps ensure consistency and facilitates the job of reviewers, reducing discussions and generally speeding things up. \ No newline at end of file diff --git a/content/en/docs/Contribute/style/content-guide.md b/content/en/docs/Contribute/style/content-guide.md deleted file mode 100644 index 1bc311fc1f4c..000000000000 --- a/content/en/docs/Contribute/style/content-guide.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Documentation Content Guide -linktitle: Content guide -content_type: concept -weight: 10 ---- - - - -This page contains guidelines for Kubernetes documentation. - -If you have questions about what's allowed, join the #sig-docs channel in -[Kubernetes Slack](https://slack.k8s.io/) and ask! - -You can register for Kubernetes Slack at https://slack.k8s.io/. - -For information on creating new content for the Kubernetes -docs, follow the [style guide](/docs/contribute/style/style-guide). - - - -## Overview - -Source for the Kubernetes website, including the docs, resides in the -[kubernetes/website](https://github.com/kubernetes/website) repository. - -Located in the `kubernetes/website/content//docs` folder, the -majority of Kubernetes documentation is specific to the [Kubernetes -project](https://github.com/kubernetes/kubernetes). - -## What's allowed - -Kubernetes docs allow content for third-party projects only when: - -- Content documents software in the Kubernetes project -- Content documents software that's out of project but necessary for Kubernetes to function -- Content is canonical on kubernetes.io, or links to canonical content elsewhere - -### Third party content - -Kubernetes documentation includes applied examples of projects in the Kubernetes -project—projects that live in the [kubernetes](https://github.com/kubernetes) and -[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations. - -Links to active content in the Kubernetes project are always allowed. - -Kubernetes requires some third party content to function. Examples include container runtimes (containerd, CRI-O, Docker), -[networking policy](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) (CNI plugins), -[Ingress controllers](/docs/concepts/services-networking/ingress-controllers/), -and [logging](/docs/concepts/cluster-administration/logging/). - -Docs can link to third-party open source software (OSS) outside the Kubernetes -project only if it's necessary for Kubernetes to function. - -### Dual sourced content - -Wherever possible, Kubernetes docs link to canonical sources instead of hosting -dual-sourced content. - -Dual-sourced content requires double the effort (or more!) to maintain -and grows stale more quickly. - -{{< note >}} -If you're a maintainer for a Kubernetes project and need help hosting your own docs, -ask for help in [#sig-docs on Kubernetes Slack](https://kubernetes.slack.com/messages/C1J0BPD2M/). -{{< /note >}} - -### More information - -If you have questions about allowed content, join the [Kubernetes Slack](https://slack.k8s.io/) #sig-docs channel and ask! - -## {{% heading "whatsnext" %}} - -* Read the [Style guide](/docs/contribute/style/style-guide). diff --git a/content/en/docs/Contribute/style/content-organization.md b/content/en/docs/Contribute/style/content-organization.md deleted file mode 100644 index 351f48fe339d..000000000000 --- a/content/en/docs/Contribute/style/content-organization.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Content organization -content_type: concept -weight: 90 ---- - - - -This site uses Hugo. In Hugo, [content organization](https://gohugo.io/content-management/organization/) is a core concept. - - - -{{% note %}} -**Hugo Tip:** Start Hugo with `hugo server --navigateToChanged` for content edit-sessions. -{{% /note %}} - -## Page Lists - -### Page Order - -The documentation side menu, the documentation page browser etc. are listed using -Hugo's default sort order, which sorts by weight (from 1), date (newest first), -and finally by the link title. - -Given that, if you want to move a page or a section up, set a weight in the page's front matter: - -```yaml -title: My Page -weight: 10 -``` - -{{% note %}} -For page weights, it can be smart not to use 1, 2, 3 ..., but some other interval, -say 10, 20, 30... This allows you to insert pages where you want later. -Additionally, each weight within the same directory (section) should not be -overlapped with the other weights. This makes sure that content is always -organized correctly, especially in localized content. -{{% /note %}} - -### Documentation Main Menu - -The `Documentation` main menu is built from the sections below `docs/` with -the `main_menu` flag set in front matter of the `_index.md` section content file: - -```yaml -main_menu: true -``` - -Note that the link title is fetched from the page's `linkTitle`, so if you want -it to be something different than the title, change it in the content file: - -```yaml -main_menu: true -title: Page Title -linkTitle: Title used in links -``` - -{{% note %}} -The above needs to be done per language. If you don't see your section in the menu, -it is probably because it is not identified as a section by Hugo. Create a -`_index.md` content file in the section folder. -{{% /note %}} - -### Documentation Side Menu - -The documentation side-bar menu is built from the _current section tree_ starting below `docs/`. - -It will show all sections and their pages. - -If you don't want to list a section or page, set the `toc_hide` flag to `true` in front matter: - -```yaml -toc_hide: true -``` - -When you navigate to a section that has content, the specific section or page -(e.g. `_index.md`) is shown. Else, the first page inside that section is shown. - -### Documentation Browser - -The page browser on the documentation home page is built using all the sections -and pages that are directly below the `docs section`. - -If you don't want to list a section or page, set the `toc_hide` flag to `true` in front matter: - -```yaml -toc_hide: true -``` - -### The Main Menu - -The site links in the top-right menu -- and also in the footer -- are built by -page-lookups. This is to make sure that the page actually exists. So, if the -`case-studies` section does not exist in a site (language), it will not be linked to. - -## Page Bundles - -In addition to standalone content pages (Markdown files), Hugo supports -[Page Bundles](https://gohugo.io/content-management/page-bundles/). - -One example is [Custom Hugo Shortcodes](/docs/contribute/style/hugo-shortcodes/). -It is considered a `leaf bundle`. Everything below the directory, including the `index.md`, -will be part of the bundle. This also includes page-relative links, images that can be processed etc.: - -```bash -en/docs/home/contribute/includes -├── example1.md -├── example2.md -├── index.md -└── podtemplate.json -``` - -Another widely used example is the `includes` bundle. It sets `headless: true` in -front matter, which means that it does not get its own URL. It is only used in other pages. - -```bash -en/includes -├── default-storage-class-prereqs.md -├── index.md -├── partner-script.js -├── partner-style.css -├── task-tutorial-prereqs.md -├── user-guide-content-moved.md -└── user-guide-migration-notice.md -``` - -Some important notes to the files in the bundles: - -* For translated bundles, any missing non-content files will be inherited from - languages above. This avoids duplication. -* All the files in a bundle are what Hugo calls `Resources` and you can provide - metadata per language, such as parameters and title, even if it does not supports - front matter (YAML files etc.). - See [Page Resources Metadata](https://gohugo.io/content-management/page-resources/#page-resources-metadata). -* The value you get from `.RelPermalink` of a `Resource` is page-relative. - See [Permalinks](https://gohugo.io/content-management/urls/#permalinks). - -## Styles - -The [SASS](https://sass-lang.com/) source of the stylesheets for this site is -stored in `assets/sass` and is automatically built by Hugo. - -## {{% heading "whatsnext" %}} - -* Learn about [custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) -* Learn about the [Style guide](/docs/contribute/style/style-guide) -* Learn about the [Content guide](/docs/contribute/style/content-guide) diff --git a/content/en/docs/Contribute/style/diagram-guide.md b/content/en/docs/Contribute/style/diagram-guide.md deleted file mode 100644 index 6a0d44828f5a..000000000000 --- a/content/en/docs/Contribute/style/diagram-guide.md +++ /dev/null @@ -1,780 +0,0 @@ ---- -title: Diagram Guide -linktitle: Diagram guide -content_type: concept -weight: 60 ---- - - - -This guide shows you how to create, edit and share diagrams using the Mermaid -JavaScript library. Mermaid.js allows you to generate diagrams using a simple -markdown-like syntax inside Markdown files. You can also use Mermaid to -generate `.svg` or `.png` image files that you can add to your documentation. - -The target audience for this guide is anybody wishing to learn about Mermaid -and/or how to create and add diagrams to Kubernetes documentation. - -Figure 1 outlines the topics covered in this section. - -{{< mermaid >}} -flowchart LR -subgraph m[Mermaid.js] -direction TB -S[ ]-.- -C[build
diagrams
with markdown] --> -D[on-line
live editor] -end -A[Why are diagrams
useful?] --> m -m --> N[3 x methods
for creating
diagrams] -N --> T[Examples] -T --> X[Styling
and
captions] -X --> V[Tips] - - - - classDef box fill:#fff,stroke:#000,stroke-width:1px,color:#000; - classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 - class A,C,D,N,X,m,T,V box - class S spacewhite - -%% you can hyperlink Mermaid diagram nodes to a URL using click statements - -click A "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgc3ViZ3JhcGggbVtNZXJtYWlkLmpzXVxuICAgIGRpcmVjdGlvbiBUQlxuICAgICAgICBTWyBdLS4tXG4gICAgICAgIENbYnVpbGQ8YnI-ZGlhZ3JhbXM8YnI-d2l0aCBtYXJrZG93bl0gLS0-XG4gICAgICAgIERbb24tbGluZTxicj5saXZlIGVkaXRvcl1cbiAgICBlbmRcbiAgICBBW1doeSBhcmUgZGlhZ3JhbXM8YnI-dXNlZnVsP10gLS0-IG1cbiAgICBtIC0tPiBOWzMgeCBtZXRob2RzPGJyPmZvciBjcmVhdGluZzxicj5kaWFncmFtc11cbiAgICBOIC0tPiBUW0V4YW1wbGVzXVxuICAgIFQgLS0-IFhbU3R5bGluZzxicj5hbmQ8YnI-Y2FwdGlvbnNdXG4gICAgWCAtLT4gVltUaXBzXVxuICAgIFxuIFxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIHNwYWNld2hpdGUgZmlsbDojZmZmZmZmLHN0cm9rZTojZmZmLHN0cm9rZS13aWR0aDowcHgsY29sb3I6IzAwMFxuICAgIGNsYXNzIEEsQyxELE4sWCxtLFQsViBib3hcbiAgICBjbGFzcyBTIHNwYWNld2hpdGUiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOnRydWV9" _blank -click C "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgc3ViZ3JhcGggbVtNZXJtYWlkLmpzXVxuICAgIGRpcmVjdGlvbiBUQlxuICAgICAgICBTWyBdLS4tXG4gICAgICAgIENbYnVpbGQ8YnI-ZGlhZ3JhbXM8YnI-d2l0aCBtYXJrZG93bl0gLS0-XG4gICAgICAgIERbb24tbGluZTxicj5saXZlIGVkaXRvcl1cbiAgICBlbmRcbiAgICBBW1doeSBhcmUgZGlhZ3JhbXM8YnI-dXNlZnVsP10gLS0-IG1cbiAgICBtIC0tPiBOWzMgeCBtZXRob2RzPGJyPmZvciBjcmVhdGluZzxicj5kaWFncmFtc11cbiAgICBOIC0tPiBUW0V4YW1wbGVzXVxuICAgIFQgLS0-IFhbU3R5bGluZzxicj5hbmQ8YnI-Y2FwdGlvbnNdXG4gICAgWCAtLT4gVltUaXBzXVxuICAgIFxuIFxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIHNwYWNld2hpdGUgZmlsbDojZmZmZmZmLHN0cm9rZTojZmZmLHN0cm9rZS13aWR0aDowcHgsY29sb3I6IzAwMFxuICAgIGNsYXNzIEEsQyxELE4sWCxtLFQsViBib3hcbiAgICBjbGFzcyBTIHNwYWNld2hpdGUiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOnRydWV9" _blank -click D "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgc3ViZ3JhcGggbVtNZXJtYWlkLmpzXVxuICAgIGRpcmVjdGlvbiBUQlxuICAgICAgICBTWyBdLS4tXG4gICAgICAgIENbYnVpbGQ8YnI-ZGlhZ3JhbXM8YnI-d2l0aCBtYXJrZG93bl0gLS0-XG4gICAgICAgIERbb24tbGluZTxicj5saXZlIGVkaXRvcl1cbiAgICBlbmRcbiAgICBBW1doeSBhcmUgZGlhZ3JhbXM8YnI-dXNlZnVsP10gLS0-IG1cbiAgICBtIC0tPiBOWzMgeCBtZXRob2RzPGJyPmZvciBjcmVhdGluZzxicj5kaWFncmFtc11cbiAgICBOIC0tPiBUW0V4YW1wbGVzXVxuICAgIFQgLS0-IFhbU3R5bGluZzxicj5hbmQ8YnI-Y2FwdGlvbnNdXG4gICAgWCAtLT4gVltUaXBzXVxuICAgIFxuIFxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIHNwYWNld2hpdGUgZmlsbDojZmZmZmZmLHN0cm9rZTojZmZmLHN0cm9rZS13aWR0aDowcHgsY29sb3I6IzAwMFxuICAgIGNsYXNzIEEsQyxELE4sWCxtLFQsViBib3hcbiAgICBjbGFzcyBTIHNwYWNld2hpdGUiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOnRydWV9" _blank -click N "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgc3ViZ3JhcGggbVtNZXJtYWlkLmpzXVxuICAgIGRpcmVjdGlvbiBUQlxuICAgICAgICBTWyBdLS4tXG4gICAgICAgIENbYnVpbGQ8YnI-ZGlhZ3JhbXM8YnI-d2l0aCBtYXJrZG93bl0gLS0-XG4gICAgICAgIERbb24tbGluZTxicj5saXZlIGVkaXRvcl1cbiAgICBlbmRcbiAgICBBW1doeSBhcmUgZGlhZ3JhbXM8YnI-dXNlZnVsP10gLS0-IG1cbiAgICBtIC0tPiBOWzMgeCBtZXRob2RzPGJyPmZvciBjcmVhdGluZzxicj5kaWFncmFtc11cbiAgICBOIC0tPiBUW0V4YW1wbGVzXVxuICAgIFQgLS0-IFhbU3R5bGluZzxicj5hbmQ8YnI-Y2FwdGlvbnNdXG4gICAgWCAtLT4gVltUaXBzXVxuICAgIFxuIFxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIHNwYWNld2hpdGUgZmlsbDojZmZmZmZmLHN0cm9rZTojZmZmLHN0cm9rZS13aWR0aDowcHgsY29sb3I6IzAwMFxuICAgIGNsYXNzIEEsQyxELE4sWCxtLFQsViBib3hcbiAgICBjbGFzcyBTIHNwYWNld2hpdGUiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOnRydWV9" _blank -click T "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgc3ViZ3JhcGggbVtNZXJtYWlkLmpzXVxuICAgIGRpcmVjdGlvbiBUQlxuICAgICAgICBTWyBdLS4tXG4gICAgICAgIENbYnVpbGQ8YnI-ZGlhZ3JhbXM8YnI-d2l0aCBtYXJrZG93bl0gLS0-XG4gICAgICAgIERbb24tbGluZTxicj5saXZlIGVkaXRvcl1cbiAgICBlbmRcbiAgICBBW1doeSBhcmUgZGlhZ3JhbXM8YnI-dXNlZnVsP10gLS0-IG1cbiAgICBtIC0tPiBOWzMgeCBtZXRob2RzPGJyPmZvciBjcmVhdGluZzxicj5kaWFncmFtc11cbiAgICBOIC0tPiBUW0V4YW1wbGVzXVxuICAgIFQgLS0-IFhbU3R5bGluZzxicj5hbmQ8YnI-Y2FwdGlvbnNdXG4gICAgWCAtLT4gVltUaXBzXVxuICAgIFxuIFxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIHNwYWNld2hpdGUgZmlsbDojZmZmZmZmLHN0cm9rZTojZmZmLHN0cm9rZS13aWR0aDowcHgsY29sb3I6IzAwMFxuICAgIGNsYXNzIEEsQyxELE4sWCxtLFQsViBib3hcbiAgICBjbGFzcyBTIHNwYWNld2hpdGUiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOnRydWV9" _blank -click X "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgc3ViZ3JhcGggbVtNZXJtYWlkLmpzXVxuICAgIGRpcmVjdGlvbiBUQlxuICAgICAgICBTWyBdLS4tXG4gICAgICAgIENbYnVpbGQ8YnI-ZGlhZ3JhbXM8YnI-d2l0aCBtYXJrZG93bl0gLS0-XG4gICAgICAgIERbb24tbGluZTxicj5saXZlIGVkaXRvcl1cbiAgICBlbmRcbiAgICBBW1doeSBhcmUgZGlhZ3JhbXM8YnI-dXNlZnVsP10gLS0-IG1cbiAgICBtIC0tPiBOWzMgeCBtZXRob2RzPGJyPmZvciBjcmVhdGluZzxicj5kaWFncmFtc11cbiAgICBOIC0tPiBUW0V4YW1wbGVzXVxuICAgIFQgLS0-IFhbU3R5bGluZzxicj5hbmQ8YnI-Y2FwdGlvbnNdXG4gICAgWCAtLT4gVltUaXBzXVxuICAgIFxuIFxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIHNwYWNld2hpdGUgZmlsbDojZmZmZmZmLHN0cm9rZTojZmZmLHN0cm9rZS13aWR0aDowcHgsY29sb3I6IzAwMFxuICAgIGNsYXNzIEEsQyxELE4sWCxtLFQsViBib3hcbiAgICBjbGFzcyBTIHNwYWNld2hpdGUiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOnRydWV9" _blank -click V "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgc3ViZ3JhcGggbVtNZXJtYWlkLmpzXVxuICAgIGRpcmVjdGlvbiBUQlxuICAgICAgICBTWyBdLS4tXG4gICAgICAgIENbYnVpbGQ8YnI-ZGlhZ3JhbXM8YnI-d2l0aCBtYXJrZG93bl0gLS0-XG4gICAgICAgIERbb24tbGluZTxicj5saXZlIGVkaXRvcl1cbiAgICBlbmRcbiAgICBBW1doeSBhcmUgZGlhZ3JhbXM8YnI-dXNlZnVsP10gLS0-IG1cbiAgICBtIC0tPiBOWzMgeCBtZXRob2RzPGJyPmZvciBjcmVhdGluZzxicj5kaWFncmFtc11cbiAgICBOIC0tPiBUW0V4YW1wbGVzXVxuICAgIFQgLS0-IFhbU3R5bGluZzxicj5hbmQ8YnI-Y2FwdGlvbnNdXG4gICAgWCAtLT4gVltUaXBzXVxuICAgIFxuIFxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIHNwYWNld2hpdGUgZmlsbDojZmZmZmZmLHN0cm9rZTojZmZmLHN0cm9rZS13aWR0aDowcHgsY29sb3I6IzAwMFxuICAgIGNsYXNzIEEsQyxELE4sWCxtLFQsViBib3hcbiAgICBjbGFzcyBTIHNwYWNld2hpdGUiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOnRydWV9" _blank - -{{< /mermaid >}} - -Figure 1. Topics covered in this section. - -All you need to begin working with Mermaid is the following: - -* Basic understanding of markdown. -* Using the Mermaid live editor. -* Using [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/). -* Using the [Hugo {{}} shortcode](https://gohugo.io/content-management/shortcodes/#figure). -* Performing [Hugo local previews](/docs/contribute/new-content/open-a-pr/#preview-locally). -* Familiar with the [Contributing new content](/docs/contribute/new-content/) process. - -{{< note >}} -You can click on each diagram in this section to view the code and rendered -diagram in the Mermaid live editor. -{{< /note >}} - - - -## Why you should use diagrams in documentation - -Diagrams improve documentation clarity and comprehension. There are advantages for both the user and the contributor. - -The user benefits include: - -* __Friendly landing spot__. A detailed text-only greeting page could - intimidate users, in particular, first-time Kubernetes users. -* __Faster grasp of concepts__. A diagram can help users understand the key - points of a complex topic. Your diagram can serve as a visual learning guide - to dive into the topic details. -* __Better retention__. For some, it is easier to recall pictures rather than text. - -The contributor benefits include: - -* __Assist in developing the structure and content__ of your contribution. For - example, you can start with a simple diagram covering the high-level points - and then dive into details. -* __Expand and grow the user community__. Easily consumed documentation - augmented with diagrams attracts new users who might previously have been - reluctant to engage due to perceived complexities. - -You should consider your target audience. In addition to experienced K8s -users, you will have many who are new to Kubernetes. Even a simple diagram can -assist new users in absorbing Kubernetes concepts. They become emboldened and -more confident to further explore Kubernetes and the documentation. - -## Mermaid - -[Mermaid](https://mermaid-js.github.io/mermaid/#/) is an open source -JavaScript library that allows you to create, edit and easily share diagrams -using a simple, markdown-like syntax configured inline in Markdown files. - -The following lists features of Mermaid: - -* Simple code syntax. -* Includes a web-based tool allowing you to code and preview your diagrams. -* Supports multiple formats including flowchart, state and sequence. -* Easy collaboration with colleagues by sharing a per-diagram URL. -* Broad selection of shapes, lines, themes and styling. - -The following lists advantages of using Mermaid: - -* No need for separate, non-Mermaid diagram tools. -* Adheres to existing PR workflow. You can think of Mermaid code as just - Markdown text included in your PR. -* Simple tool builds simple diagrams. You don't want to get bogged down - (re)crafting an overly complex and detailed picture. Keep it simple! - -Mermaid provides a simple, open and transparent method for the SIG communities -to add, edit and collaborate on diagrams for new or existing documentation. - -{{< note >}} -You can still use Mermaid to create/edit diagrams even if it's not supported -in your environment. This method is called __Mermaid+SVG__ and is explained -below. -{{< /note >}} - -### Live editor - -The [Mermaid live editor](https://mermaid-js.github.io/mermaid-live-editor) is -a web-based tool that enables you to create, edit and review diagrams. - -The following lists live editor functions: - -* Displays Mermaid code and rendered diagram. -* Generates a URL for each saved diagram. The URL is displayed in the URL - field of your browser. You can share the URL with colleagues who can access - and modify the diagram. -* Option to download `.svg` or `.png` files. - -{{< note >}} -The live editor is the easiest and fastest way to create and edit Mermaid diagrams. -{{< /note >}} - -## Methods for creating diagrams - -Figure 2 outlines the three methods to generate and add diagrams. - -{{< mermaid >}} -graph TB -A[Contributor] -B[Inline

Mermaid code
added to .md file] -C[Mermaid+SVG

Add mermaid-generated
svg file to .md file] -D[External tool

Add external-tool-
generated svg file
to .md file] - - A --> B - A --> C - A --> D - - classDef box fill:#fff,stroke:#000,stroke-width:1px,color:#000; - class A,B,C,D box - -%% you can hyperlink Mermaid diagram nodes to a URL using click statements - -click A "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggVEJcbiAgICBBW0NvbnRyaWJ1dG9yXVxuICAgIEJbSW5saW5lPGJyPjxicj5NZXJtYWlkIGNvZGU8YnI-YWRkZWQgdG8gLm1kIGZpbGVdXG4gICAgQ1tNZXJtYWlkK1NWRzxicj48YnI-QWRkIG1lcm1haWQtZ2VuZXJhdGVkPGJyPnN2ZyBmaWxlIHRvIC5tZCBmaWxlXVxuICAgIERbRXh0ZXJuYWwgdG9vbDxicj48YnI-QWRkIGV4dGVybmFsLXRvb2wtPGJyPmdlbmVyYXRlZCBzdmcgZmlsZTxicj50byAubWQgZmlsZV1cblxuICAgIEEgLS0-IEJcbiAgICBBIC0tPiBDXG4gICAgQSAtLT4gRFxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMsRCBib3giLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" _blank - -click B "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggVEJcbiAgICBBW0NvbnRyaWJ1dG9yXVxuICAgIEJbSW5saW5lPGJyPjxicj5NZXJtYWlkIGNvZGU8YnI-YWRkZWQgdG8gLm1kIGZpbGVdXG4gICAgQ1tNZXJtYWlkK1NWRzxicj48YnI-QWRkIG1lcm1haWQtZ2VuZXJhdGVkPGJyPnN2ZyBmaWxlIHRvIC5tZCBmaWxlXVxuICAgIERbRXh0ZXJuYWwgdG9vbDxicj48YnI-QWRkIGV4dGVybmFsLXRvb2wtPGJyPmdlbmVyYXRlZCBzdmcgZmlsZTxicj50byAubWQgZmlsZV1cblxuICAgIEEgLS0-IEJcbiAgICBBIC0tPiBDXG4gICAgQSAtLT4gRFxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMsRCBib3giLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" _blank - -click C "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggVEJcbiAgICBBW0NvbnRyaWJ1dG9yXVxuICAgIEJbSW5saW5lPGJyPjxicj5NZXJtYWlkIGNvZGU8YnI-YWRkZWQgdG8gLm1kIGZpbGVdXG4gICAgQ1tNZXJtYWlkK1NWRzxicj48YnI-QWRkIG1lcm1haWQtZ2VuZXJhdGVkPGJyPnN2ZyBmaWxlIHRvIC5tZCBmaWxlXVxuICAgIERbRXh0ZXJuYWwgdG9vbDxicj48YnI-QWRkIGV4dGVybmFsLXRvb2wtPGJyPmdlbmVyYXRlZCBzdmcgZmlsZTxicj50byAubWQgZmlsZV1cblxuICAgIEEgLS0-IEJcbiAgICBBIC0tPiBDXG4gICAgQSAtLT4gRFxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMsRCBib3giLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" _blank - -click D "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggVEJcbiAgICBBW0NvbnRyaWJ1dG9yXVxuICAgIEJbSW5saW5lPGJyPjxicj5NZXJtYWlkIGNvZGU8YnI-YWRkZWQgdG8gLm1kIGZpbGVdXG4gICAgQ1tNZXJtYWlkK1NWRzxicj48YnI-QWRkIG1lcm1haWQtZ2VuZXJhdGVkPGJyPnN2ZyBmaWxlIHRvIC5tZCBmaWxlXVxuICAgIERbRXh0ZXJuYWwgdG9vbDxicj48YnI-QWRkIGV4dGVybmFsLXRvb2wtPGJyPmdlbmVyYXRlZCBzdmcgZmlsZTxicj50byAubWQgZmlsZV1cblxuICAgIEEgLS0-IEJcbiAgICBBIC0tPiBDXG4gICAgQSAtLT4gRFxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMsRCBib3giLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" _blank - -{{< /mermaid >}} - -Figure 2. Methods to create diagrams. - - -### Inline - -Figure 3 outlines the steps to follow for adding a diagram using the Inline -method. - -{{< mermaid >}} -graph LR -A[1. Use live editor
to create/edit
diagram] --> -B[2. Store diagram
URL somewhere] --> -C[3. Copy Mermaid code
to page markdown file] --> -D[4. Add caption] - - - classDef box fill:#fff,stroke:#000,stroke-width:1px,color:#000; - class A,B,C,D box - -%% you can hyperlink Mermaid diagram nodes to a URL using click statements - -click A "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggTFJcbiAgICBBWzEuIFVzZSBsaXZlIGVkaXRvcjxicj4gdG8gY3JlYXRlL2VkaXQ8YnI-ZGlhZ3JhbV0gLS0-XG4gICAgQlsyLiBTdG9yZSBkaWFncmFtPGJyPlVSTCBzb21ld2hlcmVdIC0tPlxuICAgIENbMy4gQ29weSBNZXJtYWlkIGNvZGU8YnI-dG8gcGFnZSBtYXJrZG93biBmaWxlXSAtLT5cbiAgICBEWzQuIEFkZCBjYXB0aW9uXVxuIFxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMsRCBib3hcbiAgICAiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" _blank - -click B "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggTFJcbiAgICBBWzEuIFVzZSBsaXZlIGVkaXRvcjxicj4gdG8gY3JlYXRlL2VkaXQ8YnI-ZGlhZ3JhbV0gLS0-XG4gICAgQlsyLiBTdG9yZSBkaWFncmFtPGJyPlVSTCBzb21ld2hlcmVdIC0tPlxuICAgIENbMy4gQ29weSBNZXJtYWlkIGNvZGU8YnI-dG8gcGFnZSBtYXJrZG93biBmaWxlXSAtLT5cbiAgICBEWzQuIEFkZCBjYXB0aW9uXVxuIFxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMsRCBib3hcbiAgICAiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" _blank - -click C "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggTFJcbiAgICBBWzEuIFVzZSBsaXZlIGVkaXRvcjxicj4gdG8gY3JlYXRlL2VkaXQ8YnI-ZGlhZ3JhbV0gLS0-XG4gICAgQlsyLiBTdG9yZSBkaWFncmFtPGJyPlVSTCBzb21ld2hlcmVdIC0tPlxuICAgIENbMy4gQ29weSBNZXJtYWlkIGNvZGU8YnI-dG8gcGFnZSBtYXJrZG93biBmaWxlXSAtLT5cbiAgICBEWzQuIEFkZCBjYXB0aW9uXVxuIFxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMsRCBib3hcbiAgICAiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" _blank - -click D "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggTFJcbiAgICBBWzEuIFVzZSBsaXZlIGVkaXRvcjxicj4gdG8gY3JlYXRlL2VkaXQ8YnI-ZGlhZ3JhbV0gLS0-XG4gICAgQlsyLiBTdG9yZSBkaWFncmFtPGJyPlVSTCBzb21ld2hlcmVdIC0tPlxuICAgIENbMy4gQ29weSBNZXJtYWlkIGNvZGU8YnI-dG8gcGFnZSBtYXJrZG93biBmaWxlXSAtLT5cbiAgICBEWzQuIEFkZCBjYXB0aW9uXVxuIFxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMsRCBib3hcbiAgICAiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" _blank - - - -{{< /mermaid >}} - -Figure 3. Inline Method steps. - - -The following lists the steps you should follow for adding a diagram using the Inline method: - -1. Create your diagram using the live editor. -2. Store the diagram URL somewhere for later access. -3. Copy the mermaid code to the location in your `.md` file where you want the diagram to appear. -4. Add a caption below the diagram using Markdown text. - -A Hugo build runs the Mermaid code and turns it into a diagram. - -{{< note >}} -You may find keeping track of diagram URLs is cumbersome. If so, make a note -in the `.md` file that the Mermaid code is self-documenting. Contributors can -copy the Mermaid code to and from the live editor for diagram edits. -{{< /note >}} - -Here is a sample code snippet contained in an `.md` file: - -``` ---- -title: My PR ---- -Figure 17 shows a simple A to B process. -some markdown text -... -{{}} - graph TB - A --> B -{{}} - -Figure 17. A to B -more text -``` -{{< note >}} -You must include the Hugo Mermaid shortcode -tags at the start and end of the Mermaid code block. You should add a diagram -caption below the diagram. -{{< /note >}} - -For more details on diagram captions, see [How to use captions](#how-to-use-captions). - -The following lists advantages of the Inline method: - -* Live editor tool. -* Easy to copy Mermaid code to and from the live editor and your `.md` file. -* No need for separate `.svg` image file handling. -* Content text, diagram code and diagram caption contained in the same `.md` file. - -You should use the [local](/docs/contribute/new-content/open-a-pr/#preview-locally) -and Netlify previews to verify the diagram is properly rendered. - -{{< caution >}} -The Mermaid live editor feature set may not support the [kubernetes/website](https://github.com/kubernetes/website) Mermaid feature set. -And please, note that contributors can mention `kubernetes/website` as `k/website`. -You might see a syntax error or a blank screen after the Hugo build. -If that is the case, consider using the Mermaid+SVG method. -{{< /caution >}} - -### Mermaid+SVG - -Figure 4 outlines the steps to follow for adding a diagram using the Mermaid+SVG method. - -{{< mermaid >}} -flowchart LR -A[1. Use live editor
to create/edit
diagram] -B[2. Store diagram
URL somewhere] -C[3. Generate .svg file
and download to
images/ folder] -subgraph w[ ] -direction TB -D[4. Use figure shortcode
to reference .svg
file in page
.md file] --> -E[5. Add caption] -end -A --> B -B --> C -C --> w - - classDef box fill:#fff,stroke:#000,stroke-width:1px,color:#000; - class A,B,C,D,E,w box - -click A "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgbGl2ZSBlZGl0b3I8YnI-IHRvIGNyZWF0ZS9lZGl0PGJyPmRpYWdyYW1dXG4gICAgQlsyLiBTdG9yZSBkaWFncmFtPGJyPlVSTCBzb21ld2hlcmVdXG4gICAgQ1szLiBHZW5lcmF0ZSAuc3ZnIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSAuc3ZnPGJyPmZpbGUgaW4gcGFnZTxicj4ubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbkEgLS0-IEJcbkIgLS0-IENcbkMgLS0-IHdcblxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzIEEsQixDLEQsRSx3IGJveFxuICAgICIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0" _blank - -click B "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgbGl2ZSBlZGl0b3I8YnI-IHRvIGNyZWF0ZS9lZGl0PGJyPmRpYWdyYW1dXG4gICAgQlsyLiBTdG9yZSBkaWFncmFtPGJyPlVSTCBzb21ld2hlcmVdXG4gICAgQ1szLiBHZW5lcmF0ZSAuc3ZnIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSAuc3ZnPGJyPmZpbGUgaW4gcGFnZTxicj4ubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbkEgLS0-IEJcbkIgLS0-IENcbkMgLS0-IHdcblxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzIEEsQixDLEQsRSx3IGJveFxuICAgICIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0" _blank - -click C "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgbGl2ZSBlZGl0b3I8YnI-IHRvIGNyZWF0ZS9lZGl0PGJyPmRpYWdyYW1dXG4gICAgQlsyLiBTdG9yZSBkaWFncmFtPGJyPlVSTCBzb21ld2hlcmVdXG4gICAgQ1szLiBHZW5lcmF0ZSAuc3ZnIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSAuc3ZnPGJyPmZpbGUgaW4gcGFnZTxicj4ubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbkEgLS0-IEJcbkIgLS0-IENcbkMgLS0-IHdcblxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzIEEsQixDLEQsRSx3IGJveFxuICAgICIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0" _blank - -click D "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgbGl2ZSBlZGl0b3I8YnI-IHRvIGNyZWF0ZS9lZGl0PGJyPmRpYWdyYW1dXG4gICAgQlsyLiBTdG9yZSBkaWFncmFtPGJyPlVSTCBzb21ld2hlcmVdXG4gICAgQ1szLiBHZW5lcmF0ZSAuc3ZnIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSAuc3ZnPGJyPmZpbGUgaW4gcGFnZTxicj4ubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbkEgLS0-IEJcbkIgLS0-IENcbkMgLS0-IHdcblxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzIEEsQixDLEQsRSx3IGJveFxuICAgICIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0" _blank - -click E "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgbGl2ZSBlZGl0b3I8YnI-IHRvIGNyZWF0ZS9lZGl0PGJyPmRpYWdyYW1dXG4gICAgQlsyLiBTdG9yZSBkaWFncmFtPGJyPlVSTCBzb21ld2hlcmVdXG4gICAgQ1szLiBHZW5lcmF0ZSAuc3ZnIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSAuc3ZnPGJyPmZpbGUgaW4gcGFnZTxicj4ubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbkEgLS0-IEJcbkIgLS0-IENcbkMgLS0-IHdcblxuICAgIGNsYXNzRGVmIGJveCBmaWxsOiNmZmYsc3Ryb2tlOiMwMDAsc3Ryb2tlLXdpZHRoOjFweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzIEEsQixDLEQsRSx3IGJveFxuICAgICIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0" _blank - - - -{{< /mermaid >}} - -Figure 4. Mermaid+SVG method steps. - -The following lists the steps you should follow for adding a diagram using the Mermaid+SVG method: - -1. Create your diagram using the live editor. -2. Store the diagram URL somewhere for later access. -3. Generate an `.svg` image file for the diagram and download it to the appropriate `images/` folder. -4. Use the `{{}}` shortcode to reference the diagram in the `.md` file. -5. Add a caption using the `{{}}` shortcode's `caption` parameter. - -For example, use the live editor to create a diagram called `boxnet`. -Store the diagram URL somewhere for later access. Generate and download a -`boxnet.svg` file to the appropriate `../images/` folder. - -Use the `{{}}` shortcode in your PR's `.md` file to reference -the `.svg` image file and add a caption. - -```json -{{}} -``` - -For more details on diagram captions, see [How to use captions](#how-to-use-captions). - -{{< note >}} -The `{{}}` shortcode is the preferred method for adding `.svg` image files -to your documentation. You can also use the standard markdown image syntax like so: -`![my boxnet diagram](static/images/boxnet.svg)`. -And you will need to add a caption below the diagram. -{{< /note >}} - -You should add the live editor URL as a comment block in the `.svg` image file using a text editor. -For example, you would include the following at the beginning of the `.svg` image file: - -``` - - -``` - -The following lists advantages of the Mermaid+SVG method: - -* Live editor tool. -* Live editor tool supports the most current Mermaid feature set. -* Employ existing [kubernetes/website](https://github.com/kubernetes/website) methods for handling `.svg` image files. -* Environment doesn't require Mermaid support. - -Be sure to check that your diagram renders properly using the -[local](/docs/contribute/new-content/open-a-pr/#preview-locally) -and Netlify previews. - -### External tool - -Figure 5 outlines the steps to follow for adding a diagram using the External Tool method. - -First, use your external tool to create the diagram and save it as an `.svg` -or `.png` image file. After that, use the same steps as the __Mermaid+SVG__ -method for adding `.svg` image files. - -{{< mermaid >}} -flowchart LR -A[1. Use external
tool to create/edit
diagram] -B[2. If possible, save
diagram coordinates
for contributor
access] -C[3. Generate .svg
or.png file
and download to
appropriate
images/ folder] -subgraph w[ ] -direction TB -D[4. Use figure shortcode
to reference svg or
png file in
page .md file] --> -E[5. Add caption] -end -A --> B -B --> C -C --> w -classDef box fill:#fff,stroke:#000,stroke-width:1px,color:#000; -class A,B,C,D,E,w box - -click A "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgZXh0ZXJuYWw8YnI-dG9vbCB0byBjcmVhdGUvZWRpdDxicj5kaWFncmFtXVxuICAgIEJbMi4gSWYgcG9zc2libGUsIHNhdmU8YnI-ZGlhZ3JhbSBjb29yZGluYXRlczxicj5mb3IgY29udHJpYnV0b3I8YnI-YWNjZXNzXVxuICAgIENbMy4gR2VuZXJhdGUgLnN2ZyA8YnI-b3IucG5nIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmFwcHJvcHJpYXRlPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSBzdmcgb3I8YnI-cG5nIGZpbGUgaW48YnI-cGFnZSAubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbiAgICBBIC0tPiBCXG4gICAgQiAtLT4gQ1xuICAgIEMgLS0-IHdcbiAgICBjbGFzc0RlZiBib3ggZmlsbDojZmZmLHN0cm9rZTojMDAwLHN0cm9rZS13aWR0aDoxcHgsY29sb3I6IzAwMDtcbiAgICBjbGFzcyBBLEIsQyxELEUsdyBib3hcbiAgICAiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" - -click B "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgZXh0ZXJuYWw8YnI-dG9vbCB0byBjcmVhdGUvZWRpdDxicj5kaWFncmFtXVxuICAgIEJbMi4gSWYgcG9zc2libGUsIHNhdmU8YnI-ZGlhZ3JhbSBjb29yZGluYXRlczxicj5mb3IgY29udHJpYnV0b3I8YnI-YWNjZXNzXVxuICAgIENbMy4gR2VuZXJhdGUgLnN2ZyA8YnI-b3IucG5nIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmFwcHJvcHJpYXRlPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSBzdmcgb3I8YnI-cG5nIGZpbGUgaW48YnI-cGFnZSAubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbiAgICBBIC0tPiBCXG4gICAgQiAtLT4gQ1xuICAgIEMgLS0-IHdcbiAgICBjbGFzc0RlZiBib3ggZmlsbDojZmZmLHN0cm9rZTojMDAwLHN0cm9rZS13aWR0aDoxcHgsY29sb3I6IzAwMDtcbiAgICBjbGFzcyBBLEIsQyxELEUsdyBib3hcbiAgICAiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" - -click C "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgZXh0ZXJuYWw8YnI-dG9vbCB0byBjcmVhdGUvZWRpdDxicj5kaWFncmFtXVxuICAgIEJbMi4gSWYgcG9zc2libGUsIHNhdmU8YnI-ZGlhZ3JhbSBjb29yZGluYXRlczxicj5mb3IgY29udHJpYnV0b3I8YnI-YWNjZXNzXVxuICAgIENbMy4gR2VuZXJhdGUgLnN2ZyA8YnI-b3IucG5nIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmFwcHJvcHJpYXRlPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSBzdmcgb3I8YnI-cG5nIGZpbGUgaW48YnI-cGFnZSAubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbiAgICBBIC0tPiBCXG4gICAgQiAtLT4gQ1xuICAgIEMgLS0-IHdcbiAgICBjbGFzc0RlZiBib3ggZmlsbDojZmZmLHN0cm9rZTojMDAwLHN0cm9rZS13aWR0aDoxcHgsY29sb3I6IzAwMDtcbiAgICBjbGFzcyBBLEIsQyxELEUsdyBib3hcbiAgICAiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" - -click D "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgZXh0ZXJuYWw8YnI-dG9vbCB0byBjcmVhdGUvZWRpdDxicj5kaWFncmFtXVxuICAgIEJbMi4gSWYgcG9zc2libGUsIHNhdmU8YnI-ZGlhZ3JhbSBjb29yZGluYXRlczxicj5mb3IgY29udHJpYnV0b3I8YnI-YWNjZXNzXVxuICAgIENbMy4gR2VuZXJhdGUgLnN2ZyA8YnI-b3IucG5nIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmFwcHJvcHJpYXRlPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSBzdmcgb3I8YnI-cG5nIGZpbGUgaW48YnI-cGFnZSAubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbiAgICBBIC0tPiBCXG4gICAgQiAtLT4gQ1xuICAgIEMgLS0-IHdcbiAgICBjbGFzc0RlZiBib3ggZmlsbDojZmZmLHN0cm9rZTojMDAwLHN0cm9rZS13aWR0aDoxcHgsY29sb3I6IzAwMDtcbiAgICBjbGFzcyBBLEIsQyxELEUsdyBib3hcbiAgICAiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" - -click E "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgQVsxLiBVc2UgZXh0ZXJuYWw8YnI-dG9vbCB0byBjcmVhdGUvZWRpdDxicj5kaWFncmFtXVxuICAgIEJbMi4gSWYgcG9zc2libGUsIHNhdmU8YnI-ZGlhZ3JhbSBjb29yZGluYXRlczxicj5mb3IgY29udHJpYnV0b3I8YnI-YWNjZXNzXVxuICAgIENbMy4gR2VuZXJhdGUgLnN2ZyA8YnI-b3IucG5nIGZpbGU8YnI-YW5kIGRvd25sb2FkIHRvPGJyPmFwcHJvcHJpYXRlPGJyPmltYWdlcy8gZm9sZGVyXVxuICAgIHN1YmdyYXBoIHdbIF1cbiAgICBkaXJlY3Rpb24gVEJcbiAgICBEWzQuIFVzZSBmaWd1cmUgc2hvcnRjb2RlPGJyPnRvIHJlZmVyZW5jZSBzdmcgb3I8YnI-cG5nIGZpbGUgaW48YnI-cGFnZSAubWQgZmlsZV0gLS0-XG4gICAgRVs1LiBBZGQgY2FwdGlvbl1cbiAgICBlbmRcbiAgICBBIC0tPiBCXG4gICAgQiAtLT4gQ1xuICAgIEMgLS0-IHdcbiAgICBjbGFzc0RlZiBib3ggZmlsbDojZmZmLHN0cm9rZTojMDAwLHN0cm9rZS13aWR0aDoxcHgsY29sb3I6IzAwMDtcbiAgICBjbGFzcyBBLEIsQyxELEUsdyBib3hcbiAgICAiLCJtZXJtYWlkIjoie1xuICBcInRoZW1lXCI6IFwiZGVmYXVsdFwiXG59IiwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ" - -{{< /mermaid >}} - -Figure 5. External Tool method steps - - -The following lists the steps you should follow for adding a diagram using the External Tool method: - -1. Use your external tool to create a diagram. -2. Save the diagram coordinates for contributor access. For example, your tool - may offer a link to the diagram image, or you could place the source code - file, such as an `.xml` file, in a public repository for later contributor access. -3. Generate and save the diagram as an `.svg` or `.png` image file. - Download this file to the appropriate `../images/` folder. -4. Use the `{{}}` shortcode to reference the diagram in the `.md` file. -5. Add a caption using the `{{}}` shortcode's `caption` parameter. - -Here is the `{{}}` shortcode for the `images/apple.svg` diagram: -```text -{{}} -``` - -If your external drawing tool permits: - -* You can incorporate multiple `.svg` or `.png` logos, icons and images into your diagram. - However, make sure you observe copyright and follow the Kubernetes documentation - [guidelines](/docs/contribute/style/content-guide/) on the use of third party content. -* You should save the diagram source coordinates for later contributor access. - For example, your tool may offer a link to the diagram image, or you could - place the source code file, such as an `.xml` file, somewhere for contributor access. - -For more information on K8s and CNCF logos and images, check out -[CNCF Artwork](https://github.com/cncf/artwork). - -The following lists advantages of the External Tool method: - -* Contributor familiarity with external tool. -* Diagrams require more detail than what Mermaid can offer. - -Don't forget to check that your diagram renders correctly using the -[local](/docs/contribute/new-content/open-a-pr/#preview-locally) and Netlify previews. - -## Examples - -This section shows several examples of Mermaid diagrams. - -{{< note >}} -The code block examples omit the Hugo Mermaid -shortcode tags. This allows you to copy the code block into the live editor -to experiment on your own. -Note that the live editor doesn't recognize Hugo shortcodes. -{{< /note >}} - -### Example 1 - Pod topology spread constraints - -Figure 6 shows the diagram appearing in the -[Pod topology spread constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/#node-labels) -page. - -{{< mermaid >}} - graph TB - subgraph "zoneB" - n3(Node3) - n4(Node4) - end - subgraph "zoneA" - n1(Node1) - n2(Node2) - end - - classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000; - classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; - classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5; - class n1,n2,n3,n4 k8s; - class zoneA,zoneB cluster; - -click n3 "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggVEJcbiAgICBzdWJncmFwaCBcInpvbmVCXCJcbiAgICAgICAgbjMoTm9kZTMpXG4gICAgICAgIG40KE5vZGU0KVxuICAgIGVuZFxuICAgIHN1YmdyYXBoIFwiem9uZUFcIlxuICAgICAgICBuMShOb2RlMSlcbiAgICAgICAgbjIoTm9kZTIpXG4gICAgZW5kXG5cbiAgICBjbGFzc0RlZiBwbGFpbiBmaWxsOiNkZGQsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICAgIGNsYXNzRGVmIGNsdXN0ZXIgZmlsbDojZmZmLHN0cm9rZTojYmJiLHN0cm9rZS13aWR0aDoycHgsY29sb3I6IzMyNmNlNTtcbiAgICBjbGFzcyBuMSxuMixuMyxuNCBrOHM7XG4gICAgY2xhc3Mgem9uZUEsem9uZUIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0" _blank - -click n4 "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggVEJcbiAgICBzdWJncmFwaCBcInpvbmVCXCJcbiAgICAgICAgbjMoTm9kZTMpXG4gICAgICAgIG40KE5vZGU0KVxuICAgIGVuZFxuICAgIHN1YmdyYXBoIFwiem9uZUFcIlxuICAgICAgICBuMShOb2RlMSlcbiAgICAgICAgbjIoTm9kZTIpXG4gICAgZW5kXG5cbiAgICBjbGFzc0RlZiBwbGFpbiBmaWxsOiNkZGQsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICAgIGNsYXNzRGVmIGNsdXN0ZXIgZmlsbDojZmZmLHN0cm9rZTojYmJiLHN0cm9rZS13aWR0aDoycHgsY29sb3I6IzMyNmNlNTtcbiAgICBjbGFzcyBuMSxuMixuMyxuNCBrOHM7XG4gICAgY2xhc3Mgem9uZUEsem9uZUIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0" _blank - -click n1 "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggVEJcbiAgICBzdWJncmFwaCBcInpvbmVCXCJcbiAgICAgICAgbjMoTm9kZTMpXG4gICAgICAgIG40KE5vZGU0KVxuICAgIGVuZFxuICAgIHN1YmdyYXBoIFwiem9uZUFcIlxuICAgICAgICBuMShOb2RlMSlcbiAgICAgICAgbjIoTm9kZTIpXG4gICAgZW5kXG5cbiAgICBjbGFzc0RlZiBwbGFpbiBmaWxsOiNkZGQsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICAgIGNsYXNzRGVmIGNsdXN0ZXIgZmlsbDojZmZmLHN0cm9rZTojYmJiLHN0cm9rZS13aWR0aDoycHgsY29sb3I6IzMyNmNlNTtcbiAgICBjbGFzcyBuMSxuMixuMyxuNCBrOHM7XG4gICAgY2xhc3Mgem9uZUEsem9uZUIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0" _blank - -click n2 "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggVEJcbiAgICBzdWJncmFwaCBcInpvbmVCXCJcbiAgICAgICAgbjMoTm9kZTMpXG4gICAgICAgIG40KE5vZGU0KVxuICAgIGVuZFxuICAgIHN1YmdyYXBoIFwiem9uZUFcIlxuICAgICAgICBuMShOb2RlMSlcbiAgICAgICAgbjIoTm9kZTIpXG4gICAgZW5kXG5cbiAgICBjbGFzc0RlZiBwbGFpbiBmaWxsOiNkZGQsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojMDAwO1xuICAgIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICAgIGNsYXNzRGVmIGNsdXN0ZXIgZmlsbDojZmZmLHN0cm9rZTojYmJiLHN0cm9rZS13aWR0aDoycHgsY29sb3I6IzMyNmNlNTtcbiAgICBjbGFzcyBuMSxuMixuMyxuNCBrOHM7XG4gICAgY2xhc3Mgem9uZUEsem9uZUIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0" _blank - -{{< /mermaid >}} - -Figure 6. Pod Topology Spread Constraints. - -Code block: - -``` -graph TB - subgraph "zoneB" - n3(Node3) - n4(Node4) - end - subgraph "zoneA" - n1(Node1) - n2(Node2) - end - - classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000; - classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; - classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5; - class n1,n2,n3,n4 k8s; - class zoneA,zoneB cluster; -``` - -### Example 2 - Ingress - -Figure 7 shows the diagram appearing in the [What is Ingress](/docs/concepts/services-networking/ingress/#what-is-ingress) page. - -{{< mermaid >}} -graph LR; -client([client])-. Ingress-managed
load balancer .->ingress[Ingress]; -ingress-->|routing rule|service[Service]; -subgraph cluster -ingress; -service-->pod1[Pod]; -service-->pod2[Pod]; -end -classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000; -classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; -classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5; -class ingress,service,pod1,pod2 k8s; -class client plain; -class cluster cluster; - -click client "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggIExSXG4gIGNsaWVudChbY2xpZW50XSktLiBJbmdyZXNzLW1hbmFnZWQgPGJyPiBsb2FkIGJhbGFuY2VyIC4tPmluZ3Jlc3NbSW5ncmVzc107XG4gIGluZ3Jlc3MtLT58cm91dGluZyBydWxlfHNlcnZpY2VbU2VydmljZV07XG4gIHN1YmdyYXBoIGNsdXN0ZXJcbiAgaW5ncmVzcztcbiAgc2VydmljZS0tPnBvZDFbUG9kXTtcbiAgc2VydmljZS0tPnBvZDJbUG9kXTtcbiAgZW5kXG4gIGNsYXNzRGVmIHBsYWluIGZpbGw6I2RkZCxzdHJva2U6I2ZmZixzdHJva2Utd2lkdGg6NHB4LGNvbG9yOiMwMDA7XG4gIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICBjbGFzc0RlZiBjbHVzdGVyIGZpbGw6I2ZmZixzdHJva2U6I2JiYixzdHJva2Utd2lkdGg6MnB4LGNvbG9yOiMzMjZjZTU7XG4gIGNsYXNzIGluZ3Jlc3Msc2VydmljZSxwb2QxLHBvZDIgazhzO1xuICBjbGFzcyBjbGllbnQgcGxhaW47XG4gIGNsYXNzIGNsdXN0ZXIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6ZmFsc2V9" _blank - -click ingress "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggIExSXG4gIGNsaWVudChbY2xpZW50XSktLiBJbmdyZXNzLW1hbmFnZWQgPGJyPiBsb2FkIGJhbGFuY2VyIC4tPmluZ3Jlc3NbSW5ncmVzc107XG4gIGluZ3Jlc3MtLT58cm91dGluZyBydWxlfHNlcnZpY2VbU2VydmljZV07XG4gIHN1YmdyYXBoIGNsdXN0ZXJcbiAgaW5ncmVzcztcbiAgc2VydmljZS0tPnBvZDFbUG9kXTtcbiAgc2VydmljZS0tPnBvZDJbUG9kXTtcbiAgZW5kXG4gIGNsYXNzRGVmIHBsYWluIGZpbGw6I2RkZCxzdHJva2U6I2ZmZixzdHJva2Utd2lkdGg6NHB4LGNvbG9yOiMwMDA7XG4gIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICBjbGFzc0RlZiBjbHVzdGVyIGZpbGw6I2ZmZixzdHJva2U6I2JiYixzdHJva2Utd2lkdGg6MnB4LGNvbG9yOiMzMjZjZTU7XG4gIGNsYXNzIGluZ3Jlc3Msc2VydmljZSxwb2QxLHBvZDIgazhzO1xuICBjbGFzcyBjbGllbnQgcGxhaW47XG4gIGNsYXNzIGNsdXN0ZXIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6ZmFsc2V9" _blank - -click service "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggIExSXG4gIGNsaWVudChbY2xpZW50XSktLiBJbmdyZXNzLW1hbmFnZWQgPGJyPiBsb2FkIGJhbGFuY2VyIC4tPmluZ3Jlc3NbSW5ncmVzc107XG4gIGluZ3Jlc3MtLT58cm91dGluZyBydWxlfHNlcnZpY2VbU2VydmljZV07XG4gIHN1YmdyYXBoIGNsdXN0ZXJcbiAgaW5ncmVzcztcbiAgc2VydmljZS0tPnBvZDFbUG9kXTtcbiAgc2VydmljZS0tPnBvZDJbUG9kXTtcbiAgZW5kXG4gIGNsYXNzRGVmIHBsYWluIGZpbGw6I2RkZCxzdHJva2U6I2ZmZixzdHJva2Utd2lkdGg6NHB4LGNvbG9yOiMwMDA7XG4gIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICBjbGFzc0RlZiBjbHVzdGVyIGZpbGw6I2ZmZixzdHJva2U6I2JiYixzdHJva2Utd2lkdGg6MnB4LGNvbG9yOiMzMjZjZTU7XG4gIGNsYXNzIGluZ3Jlc3Msc2VydmljZSxwb2QxLHBvZDIgazhzO1xuICBjbGFzcyBjbGllbnQgcGxhaW47XG4gIGNsYXNzIGNsdXN0ZXIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6ZmFsc2V9" _blank - -click pod1 "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggIExSXG4gIGNsaWVudChbY2xpZW50XSktLiBJbmdyZXNzLW1hbmFnZWQgPGJyPiBsb2FkIGJhbGFuY2VyIC4tPmluZ3Jlc3NbSW5ncmVzc107XG4gIGluZ3Jlc3MtLT58cm91dGluZyBydWxlfHNlcnZpY2VbU2VydmljZV07XG4gIHN1YmdyYXBoIGNsdXN0ZXJcbiAgaW5ncmVzcztcbiAgc2VydmljZS0tPnBvZDFbUG9kXTtcbiAgc2VydmljZS0tPnBvZDJbUG9kXTtcbiAgZW5kXG4gIGNsYXNzRGVmIHBsYWluIGZpbGw6I2RkZCxzdHJva2U6I2ZmZixzdHJva2Utd2lkdGg6NHB4LGNvbG9yOiMwMDA7XG4gIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICBjbGFzc0RlZiBjbHVzdGVyIGZpbGw6I2ZmZixzdHJva2U6I2JiYixzdHJva2Utd2lkdGg6MnB4LGNvbG9yOiMzMjZjZTU7XG4gIGNsYXNzIGluZ3Jlc3Msc2VydmljZSxwb2QxLHBvZDIgazhzO1xuICBjbGFzcyBjbGllbnQgcGxhaW47XG4gIGNsYXNzIGNsdXN0ZXIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6ZmFsc2V9" _blank - -click pod2 "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggIExSXG4gIGNsaWVudChbY2xpZW50XSktLiBJbmdyZXNzLW1hbmFnZWQgPGJyPiBsb2FkIGJhbGFuY2VyIC4tPmluZ3Jlc3NbSW5ncmVzc107XG4gIGluZ3Jlc3MtLT58cm91dGluZyBydWxlfHNlcnZpY2VbU2VydmljZV07XG4gIHN1YmdyYXBoIGNsdXN0ZXJcbiAgaW5ncmVzcztcbiAgc2VydmljZS0tPnBvZDFbUG9kXTtcbiAgc2VydmljZS0tPnBvZDJbUG9kXTtcbiAgZW5kXG4gIGNsYXNzRGVmIHBsYWluIGZpbGw6I2RkZCxzdHJva2U6I2ZmZixzdHJva2Utd2lkdGg6NHB4LGNvbG9yOiMwMDA7XG4gIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICBjbGFzc0RlZiBjbHVzdGVyIGZpbGw6I2ZmZixzdHJva2U6I2JiYixzdHJva2Utd2lkdGg6MnB4LGNvbG9yOiMzMjZjZTU7XG4gIGNsYXNzIGluZ3Jlc3Msc2VydmljZSxwb2QxLHBvZDIgazhzO1xuICBjbGFzcyBjbGllbnQgcGxhaW47XG4gIGNsYXNzIGNsdXN0ZXIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6ZmFsc2V9" _blank - - - -{{< /mermaid >}} -Figure 7. Ingress - -Code block: - -```mermaid -graph LR; - client([client])-. Ingress-managed
load balancer .->ingress[Ingress]; - ingress-->|routing rule|service[Service]; - subgraph cluster - ingress; - service-->pod1[Pod]; - service-->pod2[Pod]; - end - classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000; - classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; - classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5; - class ingress,service,pod1,pod2 k8s; - class client plain; - class cluster cluster; -``` - -### Example 3 - K8s system flow - -Figure 8 depicts a Mermaid sequence diagram showing the system flow between -K8s components to start a container. - -{{< figure src="/docs/images/diagram-guide-example-3.svg" alt="K8s system flow diagram" class="diagram-large" caption="Figure 8. K8s system flow diagram" link="https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiJSV7aW5pdDp7XCJ0aGVtZVwiOlwibmV1dHJhbFwifX0lJVxuc2VxdWVuY2VEaWFncmFtXG4gICAgYWN0b3IgbWVcbiAgICBwYXJ0aWNpcGFudCBhcGlTcnYgYXMgY29udHJvbCBwbGFuZTxicj48YnI-YXBpLXNlcnZlclxuICAgIHBhcnRpY2lwYW50IGV0Y2QgYXMgY29udHJvbCBwbGFuZTxicj48YnI-ZXRjZCBkYXRhc3RvcmVcbiAgICBwYXJ0aWNpcGFudCBjbnRybE1nciBhcyBjb250cm9sIHBsYW5lPGJyPjxicj5jb250cm9sbGVyPGJyPm1hbmFnZXJcbiAgICBwYXJ0aWNpcGFudCBzY2hlZCBhcyBjb250cm9sIHBsYW5lPGJyPjxicj5zY2hlZHVsZXJcbiAgICBwYXJ0aWNpcGFudCBrdWJlbGV0IGFzIG5vZGU8YnI-PGJyPmt1YmVsZXRcbiAgICBwYXJ0aWNpcGFudCBjb250YWluZXIgYXMgbm9kZTxicj48YnI-Y29udGFpbmVyPGJyPnJ1bnRpbWVcbiAgICBtZS0-PmFwaVNydjogMS4ga3ViZWN0bCBjcmVhdGUgLWYgcG9kLnlhbWxcbiAgICBhcGlTcnYtLT4-ZXRjZDogMi4gc2F2ZSBuZXcgc3RhdGVcbiAgICBjbnRybE1nci0-PmFwaVNydjogMy4gY2hlY2sgZm9yIGNoYW5nZXNcbiAgICBzY2hlZC0-PmFwaVNydjogNC4gd2F0Y2ggZm9yIHVuYXNzaWduZWQgcG9kcyhzKVxuICAgIGFwaVNydi0-PnNjaGVkOiA1LiBub3RpZnkgYWJvdXQgcG9kIHcgbm9kZW5hbWU9XCIgXCJcbiAgICBzY2hlZC0-PmFwaVNydjogNi4gYXNzaWduIHBvZCB0byBub2RlXG4gICAgYXBpU3J2LS0-PmV0Y2Q6IDcuIHNhdmUgbmV3IHN0YXRlXG4gICAga3ViZWxldC0-PmFwaVNydjogOC4gbG9vayBmb3IgbmV3bHkgYXNzaWduZWQgcG9kKHMpXG4gICAgYXBpU3J2LT4-a3ViZWxldDogOS4gYmluZCBwb2QgdG8gbm9kZVxuICAgIGt1YmVsZXQtPj5jb250YWluZXI6IDEwLiBzdGFydCBjb250YWluZXJcbiAgICBrdWJlbGV0LT4-YXBpU3J2OiAxMS4gdXBkYXRlIHBvZCBzdGF0dXNcbiAgICBhcGlTcnYtLT4-ZXRjZDogMTIuIHNhdmUgbmV3IHN0YXRlIiwibWVybWFpZCI6IntcbiAgXCJ0aGVtZVwiOiBcImRlZmF1bHRcIlxufSIsInVwZGF0ZUVkaXRvciI6ZmFsc2UsImF1dG9TeW5jIjp0cnVlLCJ1cGRhdGVEaWFncmFtIjp0cnVlfQ" >}} - - - -Code block: - -``` -%%{init:{"theme":"neutral"}}%% -sequenceDiagram - actor me - participant apiSrv as control plane

api-server - participant etcd as control plane

etcd datastore - participant cntrlMgr as control plane

controller
manager - participant sched as control plane

scheduler - participant kubelet as node

kubelet - participant container as node

container
runtime - me->>apiSrv: 1. kubectl create -f pod.yaml - apiSrv-->>etcd: 2. save new state - cntrlMgr->>apiSrv: 3. check for changes - sched->>apiSrv: 4. watch for unassigned pods(s) - apiSrv->>sched: 5. notify about pod w nodename=" " - sched->>apiSrv: 6. assign pod to node - apiSrv-->>etcd: 7. save new state - kubelet->>apiSrv: 8. look for newly assigned pod(s) - apiSrv->>kubelet: 9. bind pod to node - kubelet->>container: 10. start container - kubelet->>apiSrv: 11. update pod status - apiSrv-->>etcd: 12. save new state -``` - -## How to style diagrams - -You can style one or more diagram elements using well-known CSS nomenclature. -You accomplish this using two types of statements in the Mermaid code. - -* `classDef` defines a class of style attributes. -* `class` defines one or more elements to apply the class to. - -In the code for -[figure 7](https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggIExSXG4gIGNsaWVudChbY2xpZW50XSktLiBJbmdyZXNzLW1hbmFnZWQgPGJyPiBsb2FkIGJhbGFuY2VyIC4tPmluZ3Jlc3NbSW5ncmVzc107XG4gIGluZ3Jlc3MtLT58cm91dGluZyBydWxlfHNlcnZpY2VbU2VydmljZV07XG4gIHN1YmdyYXBoIGNsdXN0ZXJcbiAgaW5ncmVzcztcbiAgc2VydmljZS0tPnBvZDFbUG9kXTtcbiAgc2VydmljZS0tPnBvZDJbUG9kXTtcbiAgZW5kXG4gIGNsYXNzRGVmIHBsYWluIGZpbGw6I2RkZCxzdHJva2U6I2ZmZixzdHJva2Utd2lkdGg6NHB4LGNvbG9yOiMwMDA7XG4gIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICBjbGFzc0RlZiBjbHVzdGVyIGZpbGw6I2ZmZixzdHJva2U6I2JiYixzdHJva2Utd2lkdGg6MnB4LGNvbG9yOiMzMjZjZTU7XG4gIGNsYXNzIGluZ3Jlc3Msc2VydmljZSxwb2QxLHBvZDIgazhzO1xuICBjbGFzcyBjbGllbnQgcGxhaW47XG4gIGNsYXNzIGNsdXN0ZXIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0), -you can see examples of both. - -``` -classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; // defines style for the k8s class -class ingress,service,pod1,pod2 k8s; // k8s class is applied to elements ingress, service, pod1 and pod2. -``` - -You can include one or multiple `classDef` and `class` statements in your diagram. -You can also use the official K8s `#326ce5` hex color code for K8s components in your diagram. - -For more information on styling and classes, see -[Mermaid Styling and classes docs](https://mermaid-js.github.io/mermaid/#/flowchart?id=styling-and-classes). - -## How to use captions - -A caption is a brief description of a diagram. A title or a short description -of the diagram are examples of captions. Captions aren't meant to replace -explanatory text you have in your documentation. Rather, they serve as a -"context link" between that text and your diagram. - -The combination of some text and a diagram tied together with a caption help -provide a concise representation of the information you wish to convey to the -user. - -Without captions, you are asking the user to scan the text above or below the -diagram to figure out a meaning. This can be frustrating for the user. - -Figure 9 lays out the three components for proper captioning: diagram, diagram -caption and the diagram referral. - -{{< mermaid >}} -flowchart -A[Diagram

Inline Mermaid or
SVG image files] -B[Diagram Caption

Add Figure Number. and
Caption Text] -C[Diagram Referral

Referenence Figure Number
in text] - - classDef box fill:#fff,stroke:#000,stroke-width:1px,color:#000; - class A,B,C box - -click A "https://mermaid-js.github.io/mermaid-live-editor/edit#eyJjb2RlIjoiZmxvd2NoYXJ0XG4gICAgQVtEaWFncmFtPGJyPjxicj5JbmxpbmUgTWVybWFpZCBvcjxicj5TVkcgaW1hZ2UgZmlsZXNdXG4gICAgQltEaWFncmFtIENhcHRpb248YnI-PGJyPkFkZCBGaWd1cmUgTnVtYmVyLiBhbmQ8YnI-Q2FwdGlvbiBUZXh0XVxuICAgIENbRGlhZ3JhbSBSZWZlcnJhbDxicj48YnI-UmVmZXJlbmVuY2UgRmlndXJlIE51bWJlcjxicj5pbiB0ZXh0XVxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMgYm94IiwibWVybWFpZCI6IntcbiAgXCJ0aGVtZVwiOiBcImRlZmF1bHRcIlxufSIsInVwZGF0ZUVkaXRvciI6ZmFsc2UsImF1dG9TeW5jIjp0cnVlLCJ1cGRhdGVEaWFncmFtIjpmYWxzZX0" _blank - -click B "https://mermaid-js.github.io/mermaid-live-editor/edit#eyJjb2RlIjoiZmxvd2NoYXJ0XG4gICAgQVtEaWFncmFtPGJyPjxicj5JbmxpbmUgTWVybWFpZCBvcjxicj5TVkcgaW1hZ2UgZmlsZXNdXG4gICAgQltEaWFncmFtIENhcHRpb248YnI-PGJyPkFkZCBGaWd1cmUgTnVtYmVyLiBhbmQ8YnI-Q2FwdGlvbiBUZXh0XVxuICAgIENbRGlhZ3JhbSBSZWZlcnJhbDxicj48YnI-UmVmZXJlbmVuY2UgRmlndXJlIE51bWJlcjxicj5pbiB0ZXh0XVxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMgYm94IiwibWVybWFpZCI6IntcbiAgXCJ0aGVtZVwiOiBcImRlZmF1bHRcIlxufSIsInVwZGF0ZUVkaXRvciI6ZmFsc2UsImF1dG9TeW5jIjp0cnVlLCJ1cGRhdGVEaWFncmFtIjpmYWxzZX0" _blank - -click C "https://mermaid-js.github.io/mermaid-live-editor/edit#eyJjb2RlIjoiZmxvd2NoYXJ0XG4gICAgQVtEaWFncmFtPGJyPjxicj5JbmxpbmUgTWVybWFpZCBvcjxicj5TVkcgaW1hZ2UgZmlsZXNdXG4gICAgQltEaWFncmFtIENhcHRpb248YnI-PGJyPkFkZCBGaWd1cmUgTnVtYmVyLiBhbmQ8YnI-Q2FwdGlvbiBUZXh0XVxuICAgIENbRGlhZ3JhbSBSZWZlcnJhbDxicj48YnI-UmVmZXJlbmVuY2UgRmlndXJlIE51bWJlcjxicj5pbiB0ZXh0XVxuXG4gICAgY2xhc3NEZWYgYm94IGZpbGw6I2ZmZixzdHJva2U6IzAwMCxzdHJva2Utd2lkdGg6MXB4LGNvbG9yOiMwMDA7XG4gICAgY2xhc3MgQSxCLEMgYm94IiwibWVybWFpZCI6IntcbiAgXCJ0aGVtZVwiOiBcImRlZmF1bHRcIlxufSIsInVwZGF0ZUVkaXRvciI6ZmFsc2UsImF1dG9TeW5jIjp0cnVlLCJ1cGRhdGVEaWFncmFtIjpmYWxzZX0" _blank - -{{< /mermaid >}} -Figure 9. Caption Components. - -{{< note >}} -You should always add a caption to each diagram in your documentation. -{{< /note >}} - -**Diagram** - -The `Mermaid+SVG` and `External Tool` methods generate `.svg` image files. - -Here is the `{{}}` shortcode for the diagram defined in an -`.svg` image file saved to `/images/docs/components-of-kubernetes.svg`: - -```none -{{}} -``` - -You should pass the `src`, `alt`, `class` and `caption` values into the -`{{}}` shortcode. You can adjust the size of the diagram using -`diagram-large`, `diagram-medium` and `diagram-small` classes. - -{{< note >}} -Diagrams created using the `Inline` method don't use the `{{}}` -shortcode. The Mermaid code defines how the diagram will render on your page. -{{< /note >}} - -See [Methods for creating diagrams](#methods-for-creating-diagrams) -for more information on the different methods for creating diagrams. - -**Diagram Caption** - -Next, add a diagram caption. - -If you define your diagram in an `.svg` image file, then you should use the -`{{}}` shortcode's `caption` parameter. - -```none -{{}} -``` - -If you define your diagram using inline Mermaid code, then you should use Markdown text. - -```none -Figure 4. Kubernetes Architecture Components -``` - -The following lists several items to consider when adding diagram captions: - -* Use the `{{}}` shortcode to add a diagram caption for `Mermaid+SVG` - and `External Tool` diagrams. -* Use simple Markdown text to add a diagram caption for the `Inline` method. -* Prepend your diagram caption with `Figure NUMBER.`. You must use `Figure` - and the number must be unique for each diagram in your documentation page. - Add a period after the number. -* Add your diagram caption text after the `Figure NUMBER.` on the same line. - You must puncuate the caption with a period. Keep the caption text short. -* Position your diagram caption __BELOW__ your diagram. - -**Diagram Referral** - -Finally, you can add a diagram referral. This is used inside your text and -should precede the diagram itself. It allows a user to connect your text with -the associated diagram. The `Figure NUMBER` in your referral and caption must -match. - -You should avoid using spatial references such as `..the image below..` or -`..the following figure ..` - -Here is an example of a diagram referral: - -```text -Figure 10 depicts the components of the Kubernetes architecture. -The control plane ... -``` -Diagram referrals are optional and there are cases where they might not be -suitable. If you are not sure, add a diagram referral to your text to see if -it looks and sounds okay. When in doubt, use a diagram referral. - -**Complete picture** - -Figure 10 shows the Kubernetes Architecture diagram that includes the diagram, -diagram caption and diagram referral. The `{{}}` shortcode -renders the diagram, adds the caption and includes the optional `link` -parameter so you can hyperlink the diagram. The diagram referral is contained -in this paragraph. - -Here is the `{{}}` shortcode for this diagram: - -``` -{{}} -``` - -{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Figure 10. Kubernetes Architecture." link="https://kubernetes.io/docs/concepts/overview/components/" >}} - -## Tips - -* Always use the live editor to create/edit your diagram. - -* Always use Hugo local and Netlify previews to check out how the diagram - appears in the documentation. - -* Include diagram source pointers such as a URL, source code location, or - indicate the code is self-documenting. - -* Always use diagram captions. - -* Very helpful to include the diagram `.svg` or `.png` image and/or Mermaid - source code in issues and PRs. - -* With the `Mermaid+SVG` and `External Tool` methods, use `.svg` image files - because they stay sharp when you zoom in on the diagram. - -* Best practice for `.svg` files is to load it into an SVG editing tool and use the - "Convert text to paths" function. - This ensures that the diagram renders the same on all systems, regardless of font - availability and font rendering support. - -* No Mermaid support for additional icons or artwork. - -* Hugo Mermaid shortcodes don't work in the live editor. - -* Any time you modify a diagram in the live editor, you __must__ save it - to generate a new URL for the diagram. - -* Click on the diagrams in this section to view the code and diagram rendering - in the live editor. - -* Look over the source code of this page, `diagram-guide.md`, for more examples. - -* Check out the [Mermaid docs](https://mermaid-js.github.io/mermaid/#/) - for explanations and examples. - -Most important, __Keep Diagrams Simple__. -This will save time for you and fellow contributors, and allow for easier reading -by new and experienced users. - - - - - - - diff --git a/content/en/docs/Contribute/style/hugo-shortcodes/example1.md b/content/en/docs/Contribute/style/hugo-shortcodes/example1.md deleted file mode 100644 index 9e9f45b0a604..000000000000 --- a/content/en/docs/Contribute/style/hugo-shortcodes/example1.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Example #1 ---- - -This is an **example** content file inside the **includes** leaf bundle. - -{{< note >}} -Included content files can also contain shortcodes. -{{< /note >}} diff --git a/content/en/docs/Contribute/style/hugo-shortcodes/example2.md b/content/en/docs/Contribute/style/hugo-shortcodes/example2.md deleted file mode 100644 index bf03fb5d93d6..000000000000 --- a/content/en/docs/Contribute/style/hugo-shortcodes/example2.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Example #1 ---- - -This is another **example** content file inside the **includes** leaf bundle. - - diff --git a/content/en/docs/Contribute/style/hugo-shortcodes/index.md b/content/en/docs/Contribute/style/hugo-shortcodes/index.md deleted file mode 100644 index 2c8c10309e8a..000000000000 --- a/content/en/docs/Contribute/style/hugo-shortcodes/index.md +++ /dev/null @@ -1,410 +0,0 @@ ---- -title: Custom Hugo Shortcodes -content_type: concept -weight: 120 ---- - - -This page explains the custom Hugo shortcodes that can be used in Kubernetes Markdown documentation. - -Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes). - - - -## Feature state - -In a Markdown page (`.md` file) on this site, you can add a shortcode to -display version and state of the documented feature. - -### Feature state demo - -Below is a demo of the feature state snippet, which displays the feature as -stable in the latest Kubernetes version. - -``` -{{}} -``` - -Renders to: - -{{< feature-state state="stable" >}} - -The valid values for `state` are: - -* alpha -* beta -* deprecated -* stable - -### Feature state code - -The displayed Kubernetes version defaults to that of the page or the site. You can change the -feature state version by passing the `for_k8s_version` shortcode parameter. For example: - -``` -{{}} -``` - -Renders to: - -{{< feature-state for_k8s_version="v1.10" state="beta" >}} - -## Glossary - -There are two glossary shortcodes: `glossary_tooltip` and `glossary_definition`. - -You can reference glossary terms with an inclusion that automatically updates -and replaces content with the relevant links from [our glossary](/docs/reference/glossary/). -When the glossary term is moused-over, the glossary entry displays a tooltip. -The glossary term also displays as a link. - -As well as inclusions with tooltips, you can reuse the definitions from the glossary in -page content. - -The raw data for glossary terms is stored at -[the glossary directory](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary), -with a content file for each glossary term. - -### Glossary demo - -For example, the following include within the Markdown renders to -{{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip: - -``` -{{}} -``` - -Here's a short glossary definition: - -``` -{{}} -``` - -which renders as: -{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}} - -You can also include a full definition: - -``` -{{}} -``` - -which renders as: -{{< glossary_definition term_id="cluster" length="all" >}} - -## Links to API Reference - -You can link to a page of the Kubernetes API reference using the -`api-reference` shortcode, for example to the -{{< api-reference page="workload-resources/pod-v1" >}} reference: - -``` -{{}} -``` - -The content of the `page` parameter is the suffix of the URL of the API reference page. - - -You can link to a specific place into a page by specifying an `anchor` -parameter, for example to the {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}} -reference or the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}} -section of the page: - -``` -{{}} -{{}} -``` - - -You can change the text of the link by specifying a `text` parameter, for -example by linking to the -{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variables">}} -section of the page: - -``` -{{}} -``` - -## Table captions - -You can make tables more accessible to screen readers by adding a table caption. To add a -[caption](https://www.w3schools.com/tags/tag_caption.asp) to a table, -enclose the table with a `table` shortcode and specify the caption with the `caption` parameter. - -{{< note >}} -Table captions are visible to screen readers but invisible when viewed in standard HTML. -{{< /note >}} - -Here's an example: - -```go-html-template -{{}} -Parameter | Description | Default -:---------|:------------|:------- -`timeout` | The timeout for requests | `30s` -`logLevel` | The log level for log output | `INFO` -{{< /table */>}} -``` - -The rendered table looks like this: - -{{< table caption="Configuration parameters" >}} -Parameter | Description | Default -:---------|:------------|:------- -`timeout` | The timeout for requests | `30s` -`logLevel` | The log level for log output | `INFO` -{{< /table >}} - -If you inspect the HTML for the table, you should see this element immediately -after the opening `` element: - -```html - -``` - -## Tabs - -In a markdown page (`.md` file) on this site, you can add a tab set to display -multiple flavors of a given solution. - -The `tabs` shortcode takes these parameters: - -* `name`: The name as shown on the tab. -* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo - what code language to use for highlighting. -* `include`: The file to include in the tab. If the tab lives in a Hugo - [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), - the file -- which can be any MIME type supported by Hugo -- is looked up in the bundle itself. - If not, the content page that needs to be included is looked up relative to the current page. - Note that with the `include`, you do not have any shortcode inner content and must use the - self-closing syntax. For example, - `{{}}`. The language needs to be specified - under `codelang` or the language is taken based on the file name. - Non-content files are code-highlighted by default. -* If your inner content is markdown, you must use the `%`-delimiter to surround the tab. - For example, `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}` -* You can combine the variations mentioned above inside a tab set. - -Below is a demo of the tabs shortcode. - -{{< note >}} -The tab **name** in a `tabs` definition must be unique within a content page. -{{< /note >}} - -### Tabs demo: Code highlighting - -```go-text-template -{{}} -{{< tab name="Tab 1" codelang="bash" >}} -echo "This is tab 1." -{{< /tab >}} -{{< tab name="Tab 2" codelang="go" >}} -println "This is tab 2." -{{< /tab >}} -{{< /tabs */>}} -``` - -Renders to: - -{{< tabs name="tab_with_code" >}} -{{< tab name="Tab 1" codelang="bash" >}} -echo "This is tab 1." -{{< /tab >}} -{{< tab name="Tab 2" codelang="go" >}} -println "This is tab 2." -{{< /tab >}} -{{< /tabs >}} - -### Tabs demo: Inline Markdown and HTML - -```go-html-template -{{}} -{{% tab name="Markdown" %}} -This is **some markdown.** -{{< note >}} -It can even contain shortcodes. -{{< /note >}} -{{% /tab %}} -{{< tab name="HTML" >}} -
-

Plain HTML

-

This is some plain HTML.

-
-{{< /tab >}} -{{< /tabs */>}} -``` - -Renders to: - -{{< tabs name="tab_with_md" >}} -{{% tab name="Markdown" %}} -This is **some markdown.** - -{{< note >}} -It can even contain shortcodes. -{{< /note >}} - -{{% /tab %}} -{{< tab name="HTML" >}} -
-

Plain HTML

-

This is some plain HTML.

-
-{{< /tab >}} -{{< /tabs >}} - -### Tabs demo: File include - -```go-text-template -{{}} -{{< tab name="Content File #1" include="example1" />}} -{{< tab name="Content File #2" include="example2" />}} -{{< tab name="JSON File" include="podtemplate" />}} -{{< /tabs */>}} -``` - -Renders to: - -{{< tabs name="tab_with_file_include" >}} -{{< tab name="Content File #1" include="example1" />}} -{{< tab name="Content File #2" include="example2" />}} -{{< tab name="JSON File" include="podtemplate.json" />}} -{{< /tabs >}} - -## Source code files - -You can use the `{{%/* code_sample */%}}` shortcode to embed the contents of file in a code block to allow users to download or copy its content to their clipboard. This shortcode is used when the contents of the sample file is generic and reusable, and you want the users to try it out themselves. - -This shortcode takes in two named parameters: `language` and `file`. The mandatory parameter `file` is used to specify the path to the file being displayed. The optional parameter `language` is used to specify the programming language of the file. If the `language` parameter is not provided, the shortcode will attempt to guess the language based on the file extension. - -For example: - -```none -{{%/* code_sample language="yaml" file="application/deployment-scale.yaml" */%}} -``` - -The output is: - -{{% code_sample language="yaml" file="application/deployment-scale.yaml" %}} - -When adding a new sample file, such as a YAML file, create the file in one of the `/examples/` subdirectories where `` is the language for the page. In the markdown of your page, use the `code` shortcode: - -```none -{{%/* code_sample file="/example-yaml>" */%}} -``` -where `` is the path to the sample file to include, relative to the `examples` directory. The following shortcode references a YAML file located at `/content/en/examples/configmap/configmaps.yaml`. - -```none -{{%/* code_sample file="configmap/configmaps.yaml" */%}} -``` - -The legacy `{{%/* codenew */%}}` shortcode is being replaced by `{{%/* code_sample */%}}`. -Use `{{%/* code_sample */%}}` (not `{{%/* codenew */%}}` or `{{%/* code */%}}`) in new documentation. - -## Third party content marker - -Running Kubernetes requires third-party software. For example: you -usually need to add a -[DNS server](/docs/tasks/administer-cluster/dns-custom-nameservers/#introduction) -to your cluster so that name resolution works. - -When we link to third-party software, or otherwise mention it, -we follow the [content guide](/docs/contribute/style/content-guide/) -and we also mark those third party items. - -Using these shortcodes adds a disclaimer to any documentation page -that uses them. - -### Lists {#third-party-content-list} - -For a list of several third-party items, add: -``` -{{%/* thirdparty-content */%}} -``` -just below the heading for the section that includes all items. - -### Items {#third-party-content-item} - -If you have a list where most of the items refer to in-project -software (for example: Kubernetes itself, and the separate -[Descheduler](https://github.com/kubernetes-sigs/descheduler) -component), then there is a different form to use. - -Add the shortcode: -``` -{{%/* thirdparty-content single="true" */%}} -``` - -before the item, or just below the heading for the specific item. - -## Version strings - -To generate a version string for inclusion in the documentation, you can choose from -several version shortcodes. Each version shortcode displays a version string derived from -the value of a version parameter found in the site configuration file, `hugo.toml`. -The two most commonly used version parameters are `latest` and `version`. - -### `{{}}` - -The `{{}}` shortcode generates the value of the current -version of the Kubernetes documentation from the `version` site parameter. The -`param` shortcode accepts the name of one site parameter, in this case: -`version`. - -{{< note >}} -In previously released documentation, `latest` and `version` parameter values -are not equivalent. After a new version is released, `latest` is incremented -and the value of `version` for the documentation set remains unchanged. For -example, a previously released version of the documentation displays `version` -as `v1.19` and `latest` as `v1.20`. -{{< /note >}} - -Renders to: - -{{< param "version" >}} - -### `{{}}` - -The `{{}}` shortcode returns the value of the `latest` site parameter. -The `latest` site parameter is updated when a new version of the documentation is released. -This parameter does not always match the value of `version` in a documentation set. - -Renders to: - -{{< latest-version >}} - -### `{{}}` - -The `{{}}` shortcode generates the value of `latest` -without the "v" prefix. - -Renders to: - -{{< latest-semver >}} - -### `{{}}` - -The `{{}}` shortcode checks if the `min-kubernetes-server-version` -page parameter is present and then uses this value to compare to `version`. - -Renders to: - -{{< version-check >}} - -### `{{}}` - -The `{{}}` shortcode generates a version string -from `latest` and removes the "v" prefix. The shortcode prints a new URL for -the release note CHANGELOG page with the modified version string. - -Renders to: - -{{< latest-release-notes >}} - -## {{% heading "whatsnext" %}} - -* Learn about [Hugo](https://gohugo.io/). -* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/). -* Learn about [page content types](/docs/contribute/style/page-content-types/). -* Learn about [opening a pull request](/docs/contribute/new-content/open-a-pr/). -* Learn about [advanced contributing](/docs/contribute/advanced/). diff --git a/content/en/docs/Contribute/style/hugo-shortcodes/podtemplate.json b/content/en/docs/Contribute/style/hugo-shortcodes/podtemplate.json deleted file mode 100644 index bd4327414a10..000000000000 --- a/content/en/docs/Contribute/style/hugo-shortcodes/podtemplate.json +++ /dev/null @@ -1,22 +0,0 @@ - { - "apiVersion": "v1", - "kind": "PodTemplate", - "metadata": { - "name": "nginx" - }, - "template": { - "metadata": { - "labels": { - "name": "nginx" - }, - "generateName": "nginx-" - }, - "spec": { - "containers": [{ - "name": "nginx", - "image": "dockerfile/nginx", - "ports": [{"containerPort": 80}] - }] - } - } - } diff --git a/content/en/docs/Contribute/style/page-content-types.md b/content/en/docs/Contribute/style/page-content-types.md deleted file mode 100644 index ada2274d9974..000000000000 --- a/content/en/docs/Contribute/style/page-content-types.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Page content types -content_type: concept -weight: 80 ---- - - - -The Kubernetes documentation follows several types of page content: - -- Concept -- Task -- Tutorial -- Reference - - - -## Content sections - -Each page content type contains a number of sections defined by -Markdown comments and HTML headings. You can add content headings to -your page with the `heading` shortcode. The comments and headings help -maintain the structure of the page content types. - -Examples of Markdown comments defining page content sections: - -```markdown - -``` - -```markdown - -``` - -To create common headings in your content pages, use the `heading` shortcode with -a heading string. - -Examples of heading strings: - -- whatsnext -- prerequisites -- objectives -- cleanup -- synopsis -- seealso -- options - -For example, to create a `whatsnext` heading, add the heading shortcode with the "whatsnext" string: - -```none -## {{%/* heading "whatsnext" */%}} -``` - -You can declare a `prerequisites` heading as follows: - -```none -## {{%/* heading "prerequisites" */%}} -``` - -The `heading` shortcode expects one string parameter. -The heading string parameter matches the prefix of a variable in the `i18n/.toml` files. -For example: - -`i18n/en.toml`: - -```toml -[whatsnext_heading] -other = "What's next" -``` - -`i18n/ko.toml`: - -```toml -[whatsnext_heading] -other = "다음 내용" -``` - -## Content types - -Each content type informally defines its expected page structure. -Create page content with the suggested page sections. - -### Concept - -A concept page explains some aspect of Kubernetes. For example, a concept -page might describe the Kubernetes Deployment object and explain the role it -plays as an application once it is deployed, scaled, and updated. Typically, concept -pages don't include sequences of steps, but instead provide links to tasks or -tutorials. - -To write a new concept page, create a Markdown file in a subdirectory of the -`/content/en/docs/concepts` directory, with the following characteristics: - -Concept pages are divided into three sections: - -| Page section | -|---------------| -| overview | -| body | -| whatsnext | - -The `overview` and `body` sections appear as comments in the concept page. -You can add the `whatsnext` section to your page with the `heading` shortcode. - -Fill each section with content. Follow these guidelines: - -- Organize content with H2 and H3 headings. -- For `overview`, set the topic's context with a single paragraph. -- For `body`, explain the concept. -- For `whatsnext`, provide a bulleted list of topics (5 maximum) to learn more about the concept. - -[Annotations](/docs/concepts/overview/working-with-objects/annotations/) is a published example of a concept page. - -### Task - -A task page shows how to do a single thing, typically by giving a short -sequence of steps. Task pages have minimal explanation, but often provide links -to conceptual topics that provide related background and knowledge. - -To write a new task page, create a Markdown file in a subdirectory of the -`/content/en/docs/tasks` directory, with the following characteristics: - -| Page section | -|---------------| -| overview | -| prerequisites | -| steps | -| discussion | -| whatsnext | - -The `overview`, `steps`, and `discussion` sections appear as comments in the task page. -You can add the `prerequisites` and `whatsnext` sections to your page -with the `heading` shortcode. - -Within each section, write your content. Use the following guidelines: - -- Use a minimum of H2 headings (with two leading `#` characters). The sections - themselves are titled automatically by the template. -- For `overview`, use a paragraph to set context for the entire topic. -- For `prerequisites`, use bullet lists when possible. Start adding additional - prerequisites below the `include`. The default prerequisites include a running Kubernetes cluster. -- For `steps`, use numbered lists. -- For discussion, use normal content to expand upon the information covered - in `steps`. -- For `whatsnext`, give a bullet list of up to 5 topics the reader might be - interested in reading next. - -An example of a published task topic is [Using an HTTP proxy to access the Kubernetes API](/docs/tasks/extend-kubernetes/http-proxy-access-api/). - -### Tutorial - -A tutorial page shows how to accomplish a goal that is larger than a single -task. Typically a tutorial page has several sections, each of which has a -sequence of steps. For example, a tutorial might provide a walkthrough of a -code sample that illustrates a certain feature of Kubernetes. Tutorials can -include surface-level explanations, but should link to related concept topics -for deep explanations. - -To write a new tutorial page, create a Markdown file in a subdirectory of the -`/content/en/docs/tutorials` directory, with the following characteristics: - -| Page section | -|---------------| -| overview | -| prerequisites | -| objectives | -| lessoncontent | -| cleanup | -| whatsnext | - -The `overview`, `objectives`, and `lessoncontent` sections appear as comments in the tutorial page. -You can add the `prerequisites`, `cleanup`, and `whatsnext` sections to your page -with the `heading` shortcode. - -Within each section, write your content. Use the following guidelines: - -- Use a minimum of H2 headings (with two leading `#` characters). The sections - themselves are titled automatically by the template. -- For `overview`, use a paragraph to set context for the entire topic. -- For `prerequisites`, use bullet lists when possible. Add additional - prerequisites below the ones included by default. -- For `objectives`, use bullet lists. -- For `lessoncontent`, use a mix of numbered lists and narrative content as - appropriate. -- For `cleanup`, use numbered lists to describe the steps to clean up the - state of the cluster after finishing the task. -- For `whatsnext`, give a bullet list of up to 5 topics the reader might be - interested in reading next. - -An example of a published tutorial topic is -[Running a Stateless Application Using a Deployment](/docs/tasks/run-application/run-stateless-application-deployment/). - -### Reference - -A component tool reference page shows the description and flag options output for -a Kubernetes component tool. Each page generates from scripts using the component tool commands. - -A tool reference page has several possible sections: - -| Page section | -|------------------------------| -| synopsis | -| options | -| options from parent commands | -| examples | -| seealso | - -Examples of published tool reference pages are: - -- [kubeadm init](/docs/reference/setup-tools/kubeadm/kubeadm-init/) -- [kube-apiserver](/docs/reference/command-line-tools-reference/kube-apiserver/) -- [kubectl](/docs/reference/kubectl/kubectl/) - -## {{% heading "whatsnext" %}} - -- Learn about the [Style guide](/docs/contribute/style/style-guide/) -- Learn about the [Content guide](/docs/contribute/style/content-guide/) -- Learn about [content organization](/docs/contribute/style/content-organization/) diff --git a/content/en/docs/Contribute/style/write-new-topic.md b/content/en/docs/Contribute/style/write-new-topic.md deleted file mode 100644 index 4204e937dda1..000000000000 --- a/content/en/docs/Contribute/style/write-new-topic.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Writing a new topic -content_type: task -weight: 70 ---- - - -This page shows how to create a new topic for the Kubernetes docs. - - -## {{% heading "prerequisites" %}} - -Create a fork of the Kubernetes documentation repository as described in -[Open a PR](/docs/contribute/new-content/open-a-pr/). - - - - -## Choosing a page type - -As you prepare to write a new topic, think about the page type that would fit your content the best: - -{{< table caption = "Guidelines for choosing a page type" >}} -Type | Description -:--- | :---------- -Concept | A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application while it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see Nodes. -Task | A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see Configure a Pod to Use a Volume for Storage. For an example of a longer task page, see Configure Liveness and Readiness Probes -Tutorial | A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features. -{{< /table >}} - -### Creating a new page - -Use a [content type](/docs/contribute/style/page-content-types/) for each new page -that you write. The docs site provides templates or -[Hugo archetypes](https://gohugo.io/content-management/archetypes/) to create -new content pages. To create a new type of page, run `hugo new` with the path to the file -you want to create. For example: - -``` -hugo new docs/concepts/my-first-concept.md -``` - -## Choosing a title and filename - -Choose a title that has the keywords you want search engines to find. -Create a filename that uses the words in your title separated by hyphens. -For example, the topic with title -[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/extend-kubernetes/http-proxy-access-api/) -has filename `http-proxy-access-api.md`. You don't need to put -"kubernetes" in the filename, because "kubernetes" is already in the -URL for the topic, for example: - - /docs/tasks/extend-kubernetes/http-proxy-access-api/ - -## Adding the topic title to the front matter - -In your topic, put a `title` field in the -[front matter](https://gohugo.io/content-management/front-matter/). -The front matter is the YAML block that is between the -triple-dashed lines at the top of the page. Here's an example: - - --- - title: Using an HTTP Proxy to Access the Kubernetes API - --- - -## Choosing a directory - -Depending on your page type, put your new file in a subdirectory of one of these: - -* /content/en/docs/tasks/ -* /content/en/docs/tutorials/ -* /content/en/docs/concepts/ - -You can put your file in an existing subdirectory, or you can create a new -subdirectory. - -## Placing your topic in the table of contents - -The table of contents is built dynamically using the directory structure of the -documentation source. The top-level directories under `/content/en/docs/` create -top-level navigation, and subdirectories each have entries in the table of -contents. - -Each subdirectory has a file `_index.md`, which represents the "home" page for -a given subdirectory's content. The `_index.md` does not need a template. It -can contain overview content about the topics in the subdirectory. - -Other files in a directory are sorted alphabetically by default. This is almost -never the best order. To control the relative sorting of topics in a -subdirectory, set the `weight:` front-matter key to an integer. Typically, we -use multiples of 10, to account for adding topics later. For instance, a topic -with weight `10` will come before one with weight `20`. - -## Embedding code in your topic - -If you want to include some code in your topic, you can embed the code in your -file directly using the markdown code block syntax. This is recommended for the -following cases (not an exhaustive list): - -- The code shows the output from a command such as - `kubectl get deploy mydeployment -o json | jq '.status'`. -- The code is not generic enough for users to try out. As an example, you can - embed the YAML - file for creating a Pod which depends on a specific - [FlexVolume](/docs/concepts/storage/volumes/#flexvolume-deprecated) implementation. -- The code is an incomplete example because its purpose is to highlight a - portion of a larger file. For example, when describing ways to - customize a [RoleBinding](/docs/reference/access-authn-authz/rbac/#role-binding-examples), - you can provide a short snippet directly in your topic file. -- The code is not meant for users to try out due to other reasons. For example, - when describing how a new attribute should be added to a resource using the - `kubectl edit` command, you can provide a short example that includes only - the attribute to add. - -## Including code from another file - -Another way to include code in your topic is to create a new, complete sample -file (or group of sample files) and then reference the sample from your topic. -Use this method to include sample YAML files when the sample is generic and -reusable, and you want the reader to try it out themselves. - -When adding a new standalone sample file, such as a YAML file, place the code in -one of the `/examples/` subdirectories where `` is the language for -the topic. In your topic file, use the `code_sample` shortcode: - -```none -{{%/* code_sample file="/my-example-yaml>" */%}} -``` -where `` is the path to the file to include, relative to the -`examples` directory. The following Hugo shortcode references a YAML -file located at `/content/en/examples/pods/storage/gce-volume.yaml`. - -```none -{{%/* code_sample file="pods/storage/gce-volume.yaml" */%}} -``` - -## Showing how to create an API object from a configuration file - -If you need to demonstrate how to create an API object based on a -configuration file, place the configuration file in one of the subdirectories -under `/examples`. - -In your topic, show this command: - -``` -kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml -``` - -{{< note >}} -When adding new YAML files to the `/examples` directory, make -sure the file is also included into the `/examples_test.go` file. The -Travis CI for the Website automatically runs this test case when PRs are -submitted to ensure all examples pass the tests. -{{< /note >}} - -For an example of a topic that uses this technique, see -[Running a Single-Instance Stateful Application](/docs/tasks/run-application/run-single-instance-stateful-application/). - -## Adding images to a topic - -Put image files in the `/images` directory. The preferred -image format is SVG. - - - -## {{% heading "whatsnext" %}} - -* Learn about [using page content types](/docs/contribute/style/page-content-types/). -* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/). -
Configuration parameters