From 74919489e35db48d0993d5619cb950f05b7e7fe2 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 11:06:01 +0100 Subject: [PATCH 01/62] Create folder and index --- content/en/docs/Contribute/_index.md | 6 ++++++ .../_index.md => Contribute/acknowledgements.md} | 0 2 files changed, 6 insertions(+) create mode 100644 content/en/docs/Contribute/_index.md rename content/en/docs/{acknowledgements/_index.md => Contribute/acknowledgements.md} (100%) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md new file mode 100644 index 000000000000..18552a4f8393 --- /dev/null +++ b/content/en/docs/Contribute/_index.md @@ -0,0 +1,6 @@ +--- +title: Contribute +description: Learn how to contribute to OpenTelemetry documentation. +weight: 200 +cSpell:ignore: +--- \ No newline at end of file diff --git a/content/en/docs/acknowledgements/_index.md b/content/en/docs/Contribute/acknowledgements.md similarity index 100% rename from content/en/docs/acknowledgements/_index.md rename to content/en/docs/Contribute/acknowledgements.md From 343d140bf97c13c1918fe2737ae0373e0e41f117 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 12:08:15 +0100 Subject: [PATCH 02/62] Initial structure and index --- content/en/docs/Contribute/_index.md | 46 +- .../new-content/blogs-case-studies.md | 199 +++++ .../Contribute/new-content/new-features.md | 143 ++++ .../docs/Contribute/new-content/open-a-pr.md | 628 ++++++++++++++ .../Contribute/roles-and-responsibilities.md | 237 ++++++ 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 +++++ .../en/docs/Contribute/style/style-guide.md | 674 +++++++++++++++ .../docs/Contribute/style/write-new-topic.md | 170 ++++ .../Contribute/suggesting-improvements.md | 67 ++ 17 files changed, 3835 insertions(+), 3 deletions(-) create mode 100644 content/en/docs/Contribute/new-content/blogs-case-studies.md create mode 100644 content/en/docs/Contribute/new-content/new-features.md create mode 100644 content/en/docs/Contribute/new-content/open-a-pr.md create mode 100644 content/en/docs/Contribute/roles-and-responsibilities.md create mode 100644 content/en/docs/Contribute/style/_index.md create mode 100644 content/en/docs/Contribute/style/content-guide.md create mode 100644 content/en/docs/Contribute/style/content-organization.md create mode 100644 content/en/docs/Contribute/style/diagram-guide.md create mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/example1.md create mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/example2.md create mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/index.md create mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/podtemplate.json create mode 100644 content/en/docs/Contribute/style/page-content-types.md create mode 100644 content/en/docs/Contribute/style/style-guide.md create mode 100644 content/en/docs/Contribute/style/write-new-topic.md create mode 100644 content/en/docs/Contribute/suggesting-improvements.md diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 18552a4f8393..851cc0199d80 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -1,6 +1,46 @@ --- title: Contribute -description: Learn how to contribute to OpenTelemetry documentation. +description: Learn how to contribute to the OpenTelemetry documentation. weight: 200 -cSpell:ignore: ---- \ No newline at end of file +cSpell:ignore: +--- + +This website is maintained by +[OpenTelemetry SIG Comms](/docs/contribute/#get-involved-with-sig-comms). + +OpenTelemetry documentation contributors: + +- Improve existing content. +- Create new content. +- Update the OpenTelemetry Registry. +- Improve the code that builds the site. + +See also the general +[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) +, which provides details on the Contributor License Agreement and the Code of +Conduct. + +## Get started + +You can open an issue about OpenTelemetry documentation, or contribute a change +with a pull request (PR) to the +[`open-telemetry/opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). + +To contribute, you need to be familiar with the following techs and tools: + +* [git](https://git-scm.com/) +* [GitHub](https://lab.github.com/) +* Markdown +* YAML + +For technical details concerning how the documentation is built and tested +locally, see the +[CONTRIBUTING.md](https://github.com/open-telemetry/opentelemetry.io/blob/main/CONTRIBUTING.md) +file. + +## Other ways to contribute + +- Visit the [OpenTelemetry community site](/community/). +- Add your application to the [Registry](/ecosystem). +- Submit a [blog post or case study](/docs/contribute/new-content/blogs-case-studies/). + diff --git a/content/en/docs/Contribute/new-content/blogs-case-studies.md b/content/en/docs/Contribute/new-content/blogs-case-studies.md new file mode 100644 index 000000000000..72d234e7a84b --- /dev/null +++ b/content/en/docs/Contribute/new-content/blogs-case-studies.md @@ -0,0 +1,199 @@ +--- +title: Submitting blog posts and case studies +linktitle: Blogs and case studies +slug: blogs-case-studies +content_type: concept +weight: 30 +--- + + + + +Anyone can write a blog post and submit it for review. +Case studies require extensive review before they're approved. + + + +## The Kubernetes Blog + +The Kubernetes blog is used by the project to communicate new features, community reports, and any +news that might be relevant to the Kubernetes community. This includes end users and developers. +Most of the blog's content is about things happening in the core project, but we encourage you to +submit about things happening elsewhere in the ecosystem too! + +Anyone can write a blog post and submit it for review. + +### Submit a Post + +Blog posts should not be commercial in nature and should consist of original content that applies +broadly to the Kubernetes community. Appropriate blog content includes: + +- New Kubernetes capabilities +- Kubernetes projects updates +- Updates from Special Interest Groups +- Tutorials and walkthroughs +- Thought leadership around Kubernetes +- Kubernetes Partner OSS integration +- **Original content only** + +Unsuitable content includes: + +- Vendor product pitches +- Partner updates without an integration and customer story +- Syndicated posts (language translations ok) + +To submit a blog post, follow these steps: + +1. [Sign the CLA](https://github.com/kubernetes/community/blob/master/CLA.md) + if you have not yet done so. + +1. Have a look at the Markdown format for existing blog posts in the + [website repository](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts). + +1. Write out your blog post in a text editor of your choice. + +1. On the same link from step 2, click the Create new file button. Paste your content into the editor. + Name the file to match the proposed title of the blog post, but don’t put the date in the file name. + The blog reviewers will work with you on the final file name and the date the blog will be published. + +1. When you save the file, GitHub will walk you through the pull request process. + +1. A blog post reviewer will review your submission and work with you on feedback and final details. + When the blog post is approved, the blog will be scheduled for publication. + +### Guidelines and expectations + +- Blog posts should not be vendor pitches. + + - Articles must contain content that applies broadly to the Kubernetes community. For example, a + submission should focus on upstream Kubernetes as opposed to vendor-specific configurations. + Check the [Documentation style guide](/docs/contribute/style/content-guide/#what-s-allowed) for + what is typically allowed on Kubernetes properties. + - Links should primarily be to the official Kubernetes documentation. When using external + references, links should be diverse - For example a submission shouldn't contain only links + back to a single company's blog. + - Sometimes this is a delicate balance. The [blog team](https://kubernetes.slack.com/messages/sig-docs-blog/) + is there to give guidance on whether a post is appropriate for the Kubernetes blog, so don't + hesitate to reach out. + +- Blog posts are not published on specific dates. + + - Articles are reviewed by community volunteers. We'll try our best to accommodate specific + timing, but we make no guarantees. + - Many core parts of the Kubernetes projects submit blog posts during release windows, delaying + publication times. Consider submitting during a quieter period of the release cycle. + - If you are looking for greater coordination on post release dates, coordinating with + [CNCF marketing](https://www.cncf.io/about/contact/) is a more appropriate choice than submitting a blog post. + - Sometimes reviews can get backed up. If you feel your review isn't getting the attention it needs, + you can reach out to the blog team on the [`#sig-docs-blog` Slack channel](https://kubernetes.slack.com/messages/sig-docs-blog/) + to ask in real time. + +- Blog posts should be relevant to Kubernetes users. + + - Topics related to participation in or results of Kubernetes SIGs activities are always on + topic (see the work in the [Contributor Comms Team](https://github.com/kubernetes/community/blob/master/communication/contributor-comms/blogging-resources/blog-guidelines.md#contributor-comms-blog-guidelines) + for support on these posts). + - The components of Kubernetes are purposely modular, so tools that use existing integration + points like CNI and CSI are on topic. + - Posts about other CNCF projects may or may not be on topic. We recommend asking the blog team + before submitting a draft. + - Many CNCF projects have their own blog. These are often a better choice for posts. There are + times of major feature or milestone for a CNCF project that users would be interested in + reading on the Kubernetes blog. + - Blog posts about contributing to the Kubernetes project should be in the + [Kubernetes Contributors site](https://kubernetes.dev) + +- Blog posts should be original content + + - The official blog is not for repurposing existing content from a third party as new content. + - The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows + commercial use of the content for commercial purposes, but not the other way around. + +- Blog posts should aim to be future proof + + - Given the development velocity of the project, we want evergreen content that won't require + updates to stay accurate for the reader. + - It can be a better choice to add a tutorial or update official documentation than to write a + high level overview as a blog post. + - Consider concentrating the long technical content as a call to action of the blog post, and + focus on the problem space or why readers should care. + +### Technical Considerations for submitting a blog post + +Submissions need to be in Markdown format to be used by the [Hugo](https://gohugo.io/) generator +for the blog. There are [many resources available](https://gohugo.io/documentation/) on how to use +this technology stack. + +We recognize that this requirement makes the process more difficult for less-familiar folks to +submit, and we're constantly looking at solutions to lower this bar. If you have ideas on how to +lower the barrier, please volunteer to help out. + +The SIG Docs [blog subproject](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject) +manages the review process for blog posts. For more information, see +[Submit a post](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject#submit-a-post). + +To submit a blog post follow these directions: + +- [Open a pull request](/docs/contribute/new-content/open-a-pr/#fork-the-repo) with a new blog post. + New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/main/content/en/blog/_posts) + directory. + +- Ensure that your blog post follows the correct naming conventions and the following frontmatter + (metadata) information: + + - The Markdown file name must follow the format `YYYY-MM-DD-Your-Title-Here.md`. For example, + `2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md`. + - Do **not** include dots in the filename. A name like `2020-01-01-whats-new-in-1.19.md` causes + failures during a build. + - The front matter must include the following: + + ```yaml + --- + layout: blog + title: "Your Title Here" + date: YYYY-MM-DD + slug: text-for-URL-link-here-no-spaces + --- + ``` + + - The first or initial commit message should be a short summary of the work being done and + should stand alone as a description of the blog post. Please note that subsequent edits to + your blog will be squashed into this main commit, so it should be as useful as possible. + + - Examples of a good commit message: + - _Add blog post on the foo kubernetes feature_ + - _blog: foobar announcement_ + - Examples of bad commit message: + - _Add blog post_ + - _._ + - _initial commit_ + - _draft post_ + + - The blog team will then review your PR and give you comments on things you might need to fix. + After that the bot will merge your PR and your blog post will be published. + + - If the content of the blog post contains only content that is not expected to require updates + to stay accurate for the reader, it can be marked as evergreen and exempted from the automatic + warning about outdated content added to blog posts older than one year. + + - To mark a blog post as evergreen, add this to the front matter: + + ```yaml + evergreen: true + ``` + - Examples of content that should not be marked evergreen: + - **Tutorials** that only apply to specific releases or versions and not all future versions + - References to pre-GA APIs or features + +## Submit a case study + +Case studies highlight how organizations are using Kubernetes to solve real-world problems. The +Kubernetes marketing team and members of the {{< glossary_tooltip text="CNCF" term_id="cncf" >}} +collaborate with you on all case studies. + +Have a look at the source for the +[existing case studies](https://github.com/kubernetes/website/tree/main/content/en/case-studies). + +Refer to the [case study guidelines](https://github.com/cncf/foundation/blob/master/case-study-guidelines.md) +and submit your request as outlined in the guidelines. + diff --git a/content/en/docs/Contribute/new-content/new-features.md b/content/en/docs/Contribute/new-content/new-features.md new file mode 100644 index 000000000000..3b71e2d5316d --- /dev/null +++ b/content/en/docs/Contribute/new-content/new-features.md @@ -0,0 +1,143 @@ +--- +title: Documenting a feature for a release +linktitle: Documenting for a release +content_type: concept +main_menu: true +weight: 20 +card: + name: contribute + weight: 45 + title: Documenting a feature for a release +--- + + +Each major Kubernetes release introduces new features that require documentation. New releases also bring updates to existing features and documentation (such as upgrading a feature from alpha to beta). + +Generally, the SIG responsible for a feature submits draft documentation of the +feature as a pull request to the appropriate development branch of the +`kubernetes/website` repository, and someone on the SIG Docs team provides +editorial feedback or edits the draft directly. This section covers the branching +conventions and process used during a release by both groups. + + + + + +## For documentation contributors + +In general, documentation contributors don't write content from scratch for a release. +Instead, they work with the SIG creating a new feature to refine the draft documentation and make it release ready. + +After you've chosen a feature to document or assist, ask about it in the `#sig-docs` +Slack channel, in a weekly SIG Docs meeting, or directly on the PR filed by the +feature SIG. If you're given the go-ahead, you can edit into the PR using one of +the techniques described in +[Commit into another person's PR](/docs/contribute/review/for-approvers/#commit-into-another-person-s-pr). + +### Find out about upcoming features + +To find out about upcoming features, attend the weekly SIG Release meeting (see +the [community](/community/) page for upcoming meetings) +and monitor the release-specific documentation +in the [kubernetes/sig-release](https://github.com/kubernetes/sig-release/) +repository. Each release has a sub-directory in the [/sig-release/tree/master/releases/](https://github.com/kubernetes/sig-release/tree/master/releases) +directory. The sub-directory contains a release schedule, a draft of the release +notes, and a document listing each person on the release team. + +The release schedule contains links to all other documents, meetings, +meeting minutes, and milestones relating to the release. It also contains +information about the goals and timeline of the release, and any special +processes in place for this release. Near the bottom of the document, several +release-related terms are defined. + +This document also contains a link to the **Feature tracking sheet**, which is +the official way to find out about all new features scheduled to go into the +release. + +The release team document lists who is responsible for each release role. If +it's not clear who to talk to about a specific feature or question you have, +either attend the release meeting to ask your question, or contact the release +lead so that they can redirect you. + +The release notes draft is a good place to find out about +specific features, changes, deprecations, and more about the release. The +content is not finalized until late in the release cycle, so use caution. + +### Feature tracking sheet + +The feature tracking sheet [for a given Kubernetes release](https://github.com/kubernetes/sig-release/tree/master/releases) +lists each feature that is planned for a release. +Each line item includes the name of the feature, a link to the feature's main +GitHub issue, its stability level (Alpha, Beta, or Stable), the SIG and +individual responsible for implementing it, whether it +needs docs, a draft release note for the feature, and whether it has been +merged. Keep the following in mind: + +- Beta and Stable features are generally a higher documentation priority than + Alpha features. +- It's hard to test (and therefore to document) a feature that hasn't been merged, + or is at least considered feature-complete in its PR. +- Determining whether a feature needs documentation is a manual process. Even if + a feature is not marked as needing docs, you may need to document the feature. + +## For developers or other SIG members + +This section is information for members of other Kubernetes SIGs documenting new features +for a release. + +If you are a member of a SIG developing a new feature for Kubernetes, you need +to work with SIG Docs to be sure your feature is documented in time for the +release. Check the +[feature tracking spreadsheet](https://github.com/kubernetes/sig-release/tree/master/releases) +or check in the `#sig-release` Kubernetes Slack channel to verify scheduling details and +deadlines. + +### Open a placeholder PR + +1. Open a **draft** pull request against the +`dev-{{< skew nextMinorVersion >}}` branch in the `kubernetes/website` repository, with a small +commit that you will amend later. To create a draft pull request, use the +Create Pull Request drop-down and select **Create Draft Pull Request**, +then click **Draft Pull Request**. +2. Edit the pull request description to include links to [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) +PR(s) and [kubernetes/enhancements](https://github.com/kubernetes/enhancements) issue(s). +3. Leave a comment on the related [kubernetes/enhancements](https://github.com/kubernetes/enhancements) +issue with a link to the PR to notify the docs person managing this release that +the feature docs are coming and should be tracked for the release. + +If your feature does not need +any documentation changes, make sure the sig-release team knows this, by +mentioning it in the `#sig-release` Slack channel. If the feature does need +documentation but the PR is not created, the feature may be removed from the +milestone. + +### PR ready for review + +When ready, populate your placeholder PR with feature documentation and change +the state of the PR from draft to **ready for review**. To mark a pull request +as ready for review, navigate to the merge box and click **Ready for review**. + +Do your best to describe your feature and how to use it. If you need help structuring your documentation, ask in the `#sig-docs` Slack channel. + +When you complete your content, the documentation person assigned to your feature reviews it. +To ensure technical accuracy, the content may also require a technical review from corresponding SIG(s). +Use their suggestions to get the content to a release ready state. + +If your feature is an Alpha or Beta feature and is behind a feature gate, +make sure you add it to [Alpha/Beta Feature gates](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features) +table as part of your pull request. With new feature gates, a description of +the feature gate is also required. If your feature is GA'ed or deprecated, +make sure to move it from the +[Feature gates for Alpha/Feature](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features) table +to [Feature gates for graduated or deprecated features](/docs/reference/command-line-tools-reference/feature-gates-removed/#feature-gates-that-are-removed) +table with Alpha and Beta history intact. + +If your feature needs documentation and the first draft +content is not received, the feature may be removed from the milestone. + +### All PRs reviewed and ready to merge + +If your PR has not yet been merged into the `dev-{{< skew nextMinorVersion >}}` branch by the release deadline, work with the +docs person managing the release to get it in by the deadline. If your feature needs +documentation and the docs are not ready, the feature may be removed from the +milestone. \ No newline at end of file diff --git a/content/en/docs/Contribute/new-content/open-a-pr.md b/content/en/docs/Contribute/new-content/open-a-pr.md new file mode 100644 index 000000000000..382befe11694 --- /dev/null +++ b/content/en/docs/Contribute/new-content/open-a-pr.md @@ -0,0 +1,628 @@ +--- +title: Opening a pull request +content_type: concept +weight: 10 +card: + name: contribute + weight: 40 +--- + + + +{{< note >}} +**Code developers**: If you are documenting a new feature for an +upcoming Kubernetes release, see +[Document a new feature](/docs/contribute/new-content/new-features/). +{{< /note >}} + +To contribute new content pages or improve existing content pages, open a pull request (PR). +Make sure you follow all the requirements in the +[Before you begin](/docs/contribute/new-content/) section. + +If your change is small, or you're unfamiliar with git, read +[Changes using GitHub](#changes-using-github) to learn how to edit a page. + +If your changes are large, read [Work from a local fork](#fork-the-repo) to learn how to make +changes locally on your computer. + + + +## Changes using GitHub + +If you're less experienced with git workflows, here's an easier method of +opening a pull request. Figure 1 outlines the steps and the details follow. + + + + +{{< mermaid >}} +flowchart LR +A([fa:fa-user New
Contributor]) --- id1[(kubernetes/website
GitHub)] +subgraph tasks[Changes using GitHub] +direction TB + 0[ ] -.- + 1[1. Edit this page] --> 2[2. Use GitHub markdown
editor to make changes] + 2 --> 3[3. fill in Propose file change] + +end +subgraph tasks2[ ] +direction TB +4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] +6 --> 7[7. select Create pull request] +end + +id1 --> tasks --> tasks2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,1,2,3,4,5,6,7 grey +class 0 spacewhite +class tasks,tasks2 white +class id1 k8s +{{}} + +Figure 1. Steps for opening a PR using GitHub. + +1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. + +1. Make your changes in the GitHub markdown editor. + +1. Below the editor, fill in the **Propose file change** form. + In the first field, give your commit message a title. + In the second field, provide a description. + + {{< note >}} + Do not use any [GitHub Keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) + in your commit message. You can add those to the pull request description later. + {{< /note >}} + +1. Select **Propose file change**. + +1. Select **Create pull request**. + +1. The **Open a pull request** screen appears. Fill in the form: + + - The **Subject** field of the pull request defaults to the commit summary. + You can change it if needed. + - The **Body** contains your extended commit message, if you have one, + and some template text. Add the + details the template text asks for, then delete the extra template text. + - Leave the **Allow edits from maintainers** checkbox selected. + + {{< note >}} + PR descriptions are a great way to help reviewers understand your change. + For more information, see [Opening a PR](#open-a-pr). + {{}} + +1. Select **Create pull request**. + +### Addressing feedback in GitHub + +Before merging a pull request, Kubernetes community members review and +approve it. The `k8s-ci-robot` suggests reviewers based on the nearest +owner mentioned in the pages. If you have someone specific in mind, +leave a comment with their GitHub username in it. + +If a reviewer asks you to make changes: + +1. Go to the **Files changed** tab. +1. Select the pencil (edit) icon on any files changed by the pull request. +1. Make the changes requested. +1. Commit the changes. + +If you are waiting on a reviewer, reach out once every 7 days. You can also post a message in the +`#sig-docs` Slack channel. + +When your review is complete, a reviewer merges your PR and your changes go live a few minutes later. + +## Work from a local fork {#fork-the-repo} + +If you're more experienced with git, or if your changes are larger than a few lines, +work from a local fork. + +Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed +on your computer. You can also use a git UI application. + +Figure 2 shows the steps to follow when you work from a local fork. The details for each step follow. + + + + +{{< mermaid >}} +flowchart LR +1[Fork the kubernetes/website
repository] --> 2[Create local clone
and set upstream] +subgraph changes[Your changes] +direction TB +S[ ] -.- +3[Create a branch
example: my_new_branch] --> 3a[Make changes using
text editor] --> 4["Preview your changes
locally using Hugo
(localhost:1313)
or build container image"] +end +subgraph changes2[Commit / Push] +direction TB +T[ ] -.- +5[Commit your changes] --> 6[Push commit to
origin/my_new_branch] +end + +2 --> changes --> changes2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class 1,2,3,3a,4,5,6 grey +class S,T spacewhite +class changes,changes2 white +{{}} + +Figure 2. Working from a local fork to make your changes. + +### Fork the kubernetes/website repository + +1. Navigate to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository. +1. Select **Fork**. + +### Create a local clone and set the upstream + +1. In a terminal window, clone your fork and update the [Docsy Hugo theme](https://github.com/google/docsy#readme): + + ```shell + git clone git@github.com:/website + cd website + git submodule update --init --recursive --depth 1 + ``` + +1. Navigate to the new `website` directory. Set the `kubernetes/website` repository as the `upstream` remote: + + ```shell + cd website + + git remote add upstream https://github.com/kubernetes/website.git + ``` + +1. Confirm your `origin` and `upstream` repositories: + + ```shell + git remote -v + ``` + + Output is similar to: + + ```none + origin git@github.com:/website.git (fetch) + origin git@github.com:/website.git (push) + upstream https://github.com/kubernetes/website.git (fetch) + upstream https://github.com/kubernetes/website.git (push) + ``` + +1. Fetch commits from your fork's `origin/main` and `kubernetes/website`'s `upstream/main`: + + ```shell + git fetch origin + git fetch upstream + ``` + + This makes sure your local repository is up to date before you start making changes. + + {{< note >}} + This workflow is different than the + [Kubernetes Community GitHub Workflow](https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md). + You do not need to merge your local copy of `main` with `upstream/main` before pushing updates + to your fork. + {{< /note >}} + +### Create a branch + +1. Decide which branch base to your work on: + + - For improvements to existing content, use `upstream/main`. + - For new content about existing features, use `upstream/main`. + - For localized content, use the localization's conventions. For more information, see + [localizing Kubernetes documentation](/docs/contribute/localization/). + - For new features in an upcoming Kubernetes release, use the feature branch. For more + information, see [documenting for a release](/docs/contribute/new-content/new-features/). + - For long-running efforts that multiple SIG Docs contributors collaborate on, + like content reorganization, use a specific feature branch created for that effort. + + If you need help choosing a branch, ask in the `#sig-docs` Slack channel. + +1. Create a new branch based on the branch identified in step 1. This example assumes the base + branch is `upstream/main`: + + ```shell + git checkout -b upstream/main + ``` + +1. Make your changes using a text editor. + +At any time, use the `git status` command to see what files you've changed. + +### Commit your changes + +When you are ready to submit a pull request, commit your changes. + +1. In your local repository, check which files you need to commit: + + ```shell + git status + ``` + + Output is similar to: + + ```none + On branch + Your branch is up to date with 'origin/'. + + Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: content/en/docs/contribute/new-content/contributing-content.md + + no changes added to commit (use "git add" and/or "git commit -a") + ``` + +1. Add the files listed under **Changes not staged for commit** to the commit: + + ```shell + git add + ``` + + Repeat this for each file. + +1. After adding all the files, create a commit: + + ```shell + git commit -m "Your commit message" + ``` + + {{< note >}} + Do not use any [GitHub Keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) + in your commit message. You can add those to the pull request + description later. + {{< /note >}} + +1. Push your local branch and its new commit to your remote fork: + + ```shell + git push origin + ``` + +### Preview your changes locally {#preview-locally} + +It's a good idea to preview your changes locally before pushing them or opening a pull request. +A preview lets you catch build errors or markdown formatting problems. + +You can either build the website's container image or run Hugo locally. Building the container +image is slower but displays [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/), which can +be useful for debugging. + +{{< tabs name="tab_with_hugo" >}} +{{% tab name="Hugo in a container" %}} + +{{< note >}} +The commands below use Docker as default container engine. Set the `CONTAINER_ENGINE` environment +variable to override this behaviour. +{{< /note >}} + +1. Build the container image locally + _You only need this step if you are testing a change to the Hugo tool itself_ + + ```shell + # Run this in a terminal (if required) + make container-image + ``` + +1. Start Hugo in a container: + + ```shell + # Run this in a terminal + make container-serve + ``` + +1. In a web browser, navigate to `https://localhost:1313`. Hugo watches the + changes and rebuilds the site as needed. + +1. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, + or close the terminal window. + +{{% /tab %}} +{{% tab name="Hugo on the command line" %}} + +Alternately, install and use the `hugo` command on your computer: + +1. Install the [Hugo](https://gohugo.io/getting-started/installing/) version specified in + [`website/netlify.toml`](https://raw.githubusercontent.com/kubernetes/website/main/netlify.toml). + +1. If you have not updated your website repository, the `website/themes/docsy` directory is empty. + The site cannot build without a local copy of the theme. To update the website theme, run: + + ```shell + git submodule update --init --recursive --depth 1 + ``` + +1. In a terminal, go to your Kubernetes website repository and start the Hugo server: + + ```shell + cd /website + hugo server --buildFuture + ``` + +1. In a web browser, navigate to `https://localhost:1313`. Hugo watches the + changes and rebuilds the site as needed. + +1. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, + or close the terminal window. + +{{% /tab %}} +{{< /tabs >}} + +### Open a pull request from your fork to kubernetes/website {#open-a-pr} + +Figure 3 shows the steps to open a PR from your fork to the [kubernetes/website](https://github.com/kubernetes/website). The details follow. + +Please, note that contributors can mention `kubernetes/website` as `k/website`. + + + + +{{< mermaid >}} +flowchart LR +subgraph first[ ] +direction TB +1[1. Go to kubernetes/website repository] --> 2[2. Select New Pull Request] +2 --> 3[3. Select compare across forks] +3 --> 4[4. Select your fork from
head repository drop-down menu] +end +subgraph second [ ] +direction TB +5[5. Select your branch from
the compare drop-down menu] --> 6[6. Select Create Pull Request] +6 --> 7[7. Add a description
to your PR] +7 --> 8[8. Select Create pull request] +end + +first --> second + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +class 1,2,3,4,5,6,7,8 grey +class first,second white +{{}} + +Figure 3. Steps to open a PR from your fork to the [kubernetes/website](https://github.com/kubernetes/website). + +1. In a web browser, go to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository. +1. Select **New Pull Request**. +1. Select **compare across forks**. +1. From the **head repository** drop-down menu, select your fork. +1. From the **compare** drop-down menu, select your branch. +1. Select **Create Pull Request**. +1. Add a description for your pull request: + + - **Title** (50 characters or less): Summarize the intent of the change. + - **Description**: Describe the change in more detail. + + - If there is a related GitHub issue, include `Fixes #12345` or `Closes #12345` in the + description. GitHub's automation closes the mentioned issue after merging the PR if used. + If there are other related PRs, link those as well. + - If you want advice on something specific, include any questions you'd like reviewers to + think about in your description. + +1. Select the **Create pull request** button. + +Congratulations! Your pull request is available in [Pull requests](https://github.com/kubernetes/website/pulls). + +After opening a PR, GitHub runs automated tests and tries to deploy a preview using +[Netlify](https://www.netlify.com/). + +- If the Netlify build fails, select **Details** for more information. +- If the Netlify build succeeds, select **Details** opens a staged version of the Kubernetes + website with your changes applied. This is how reviewers check your changes. + +GitHub also automatically assigns labels to a PR, to help reviewers. You can add them too, if +needed. For more information, see [Adding and removing issue labels](/docs/contribute/review/for-approvers/#adding-and-removing-issue-labels). + +### Addressing feedback locally + +1. After making your changes, amend your previous commit: + + ```shell + git commit -a --amend + ``` + + - `-a`: commits all changes + - `--amend`: amends the previous commit, rather than creating a new one + +1. Update your commit message if needed. + +1. Use `git push origin ` to push your changes and re-run the Netlify tests. + + {{< note >}} + If you use `git commit -m` instead of amending, you must [squash your commits](#squashing-commits) + before merging. + {{< /note >}} + +#### Changes from reviewers + +Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits. + +1. Fetch commits from your remote fork and rebase your working branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + +1. After rebasing, force-push new changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +#### Merge conflicts and rebasing + +{{< note >}} +For more information, see [Git Branching - Basic Branching and Merging](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts), +[Advanced Merging](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging), or ask in the +`#sig-docs` Slack channel for help. +{{< /note >}} + +If another contributor commits changes to the same file in another PR, it can create a merge +conflict. You must resolve all merge conflicts in your PR. + +1. Update your fork and rebase your local branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + + Then force-push the changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +1. Fetch changes from `kubernetes/website`'s `upstream/main` and rebase your branch: + + ```shell + git fetch upstream + git rebase upstream/main + ``` + +1. Inspect the results of the rebase: + + ```shell + git status + ``` + + This results in a number of files marked as conflicted. + +1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. + Resolve the conflict and delete the conflict marker. + + {{< note >}} + For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). + {{< /note >}} + +1. Add the files to the changeset: + + ```shell + git add + ``` + +1. Continue the rebase: + + ```shell + git rebase --continue + ``` + +1. Repeat steps 2 to 5 as needed. + + After applying all commits, the `git status` command shows that the rebase is complete. + +1. Force-push the branch to your fork: + + ```shell + git push --force-with-lease origin + ``` + + The pull request no longer shows any conflicts. + +### Squashing commits + +{{< note >}} +For more information, see [Git Tools - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History), +or ask in the `#sig-docs` Slack channel for help. +{{< /note >}} + +If your PR has multiple commits, you must squash them into a single commit before merging your PR. +You can check the number of commits on your PR's **Commits** tab or by running the `git log` +command locally. + +{{< note >}} +This topic assumes `vim` as the command line text editor. +{{< /note >}} + +1. Start an interactive rebase: + + ```shell + git rebase -i HEAD~ + ``` + + Squashing commits is a form of rebasing. The `-i` switch tells git you want to rebase interactively. + `HEAD~}} + For more information, see [Interactive Mode](https://git-scm.com/docs/git-rebase#_interactive_mode). + {{< /note >}} + +1. Start editing the file. + + Change the original text: + + ```none + pick d875112ca Original commit + pick 4fa167b80 Address feedback 1 + pick 7d54e15ee Address feedback 2 + ``` + + To: + + ```none + pick d875112ca Original commit + squash 4fa167b80 Address feedback 1 + squash 7d54e15ee Address feedback 2 + ``` + + This squashes commits `4fa167b80 Address feedback 1` and `7d54e15ee Address feedback 2` into + `d875112ca Original commit`, leaving only `d875112ca Original commit` as a part of the timeline. + +1. Save and exit your file. + +1. Push your squashed commit: + + ```shell + git push --force-with-lease origin + ``` + +## Contribute to other repos + +The [Kubernetes project](https://github.com/kubernetes) contains 50+ repositories. Many of these +repositories contain documentation: user-facing help text, error messages, API references or code +comments. + +If you see text you'd like to improve, use GitHub to search all repositories in the Kubernetes +organization. This can help you figure out where to submit your issue or PR. + +Each repository has its own processes and procedures. Before you file an issue or submit a PR, +read that repository's `README.md`, `CONTRIBUTING.md`, and `code-of-conduct.md`, if they exist. + +Most repositories use issue and PR templates. Have a look through some open issues and PRs to get +a feel for that team's processes. Make sure to fill out the templates with as much detail as +possible when you file issues or PRs. + +## {{% heading "whatsnext" %}} + +- Read [Reviewing](/docs/contribute/review/reviewing-prs) to learn more about the review process. + diff --git a/content/en/docs/Contribute/roles-and-responsibilities.md b/content/en/docs/Contribute/roles-and-responsibilities.md new file mode 100644 index 000000000000..19c9190fd88d --- /dev/null +++ b/content/en/docs/Contribute/roles-and-responsibilities.md @@ -0,0 +1,237 @@ +--- +title: Roles and responsibilities +content_type: concept +weight: 10 +--- + + + +Anyone can contribute to Kubernetes. As your contributions to SIG Docs grow, +you can apply for different levels of membership in the community. +These roles allow you to take on more responsibility within the community. +Each role requires more time and commitment. The roles are: + +- Anyone: regular contributors to the Kubernetes documentation +- Members: can assign and triage issues and provide non-binding review on pull requests +- Reviewers: can lead reviews on documentation pull requests and can vouch for a change's quality +- Approvers: can lead reviews on documentation and merge changes + + + +## Anyone + +Anyone with a GitHub account can contribute to Kubernetes. SIG Docs welcomes all new contributors! + +Anyone can: + +- Open an issue in any [Kubernetes](https://github.com/kubernetes/) + repository, including + [`kubernetes/website`](https://github.com/kubernetes/website) +- Give non-binding feedback on a pull request +- Contribute to a localization +- Suggest improvements on [Slack](https://slack.k8s.io/) or the + [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). + +After [signing the CLA](https://github.com/kubernetes/community/blob/master/CLA.md), anyone can also: + +- Open a pull request to improve existing content, add new content, or write a blog post or case study +- Create diagrams, graphics assets, and embeddable screencasts and videos + +For more information, see [contributing new content](/docs/contribute/new-content/). + +## Members + +A member is someone who has submitted multiple pull requests to +`kubernetes/website`. Members are a part of the +[Kubernetes GitHub organization](https://github.com/kubernetes). + +Members can: + +- Do everything listed under [Anyone](#anyone) +- Use the `/lgtm` comment to add the LGTM (looks good to me) label to a pull request + + {{< note >}} + Using `/lgtm` triggers automation. If you want to provide non-binding + approval, commenting "LGTM" works too! + {{< /note >}} + +- Use the `/hold` comment to block merging for a pull request +- Use the `/assign` comment to assign a reviewer to a pull request +- Provide non-binding review on pull requests +- Use automation to triage and categorize issues +- Document new features + +### Becoming a member + +After submitting at least 5 substantial pull requests and meeting the other +[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#member): + +1. Find two [reviewers](#reviewers) or [approvers](#approvers) to + [sponsor](/docs/contribute/advanced#sponsor-a-new-contributor) your + membership. + + Ask for sponsorship in the [#sig-docs channel on Slack](https://kubernetes.slack.com) or on the + [SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). + + {{< note >}} + Don't send a direct email or Slack direct message to an individual + SIG Docs member. You must request sponsorship before submitting your application. + {{< /note >}} + +1. Open a GitHub issue in the + [`kubernetes/org`](https://github.com/kubernetes/org/) repository. Use the + **Organization Membership Request** issue template. + +1. Let your sponsors know about the GitHub issue. You can either: + - Mention their GitHub username in an issue (`@`) + - Send them the issue link using Slack or email. + + Sponsors will approve your request with a `+1` vote. Once your sponsors + approve the request, a Kubernetes GitHub admin adds you as a member. + Congratulations! + + If your membership request is not accepted you will receive feedback. + After addressing the feedback, apply again. + +1. Accept the invitation to the Kubernetes GitHub organization in your email account. + + {{< note >}} + GitHub sends the invitation to the default email address in your account. + {{< /note >}} + +## Reviewers + +Reviewers are responsible for reviewing open pull requests. Unlike member +feedback, the PR author must address reviewer feedback. Reviewers are members of the +[@kubernetes/sig-docs-{language}-reviews](https://github.com/orgs/kubernetes/teams?query=sig-docs) +GitHub team. + +Reviewers can: + +- Do everything listed under [Anyone](#anyone) and [Members](#members) +- Review pull requests and provide binding feedback + + {{< note >}} + To provide non-binding feedback, prefix your comments with a phrase like "Optionally: ". + {{< /note >}} + +- Edit user-facing strings in code +- Improve code comments + +You can be a SIG Docs reviewer, or a reviewer for docs in a specific subject area. + +### Assigning reviewers to pull requests + +Automation assigns reviewers to all pull requests. You can request a +review from a specific person by commenting: `/assign +[@_github_handle]`. + +If the assigned reviewer has not commented on the PR, another reviewer can +step in. You can also assign technical reviewers as needed. + +### Using `/lgtm` + +LGTM stands for "Looks good to me" and indicates that a pull request is +technically accurate and ready to merge. All PRs need a `/lgtm` comment from a +reviewer and a `/approve` comment from an approver to merge. + +A `/lgtm` comment from reviewer is binding and triggers automation that adds the `lgtm` label. + +### Becoming a reviewer + +When you meet the +[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer), +you can become a SIG Docs reviewer. Reviewers in other SIGs must apply +separately for reviewer status in SIG Docs. + +To apply: + +1. Open a pull request that adds your GitHub username to a section of the + [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) file + in the `kubernetes/website` repository. + + {{< note >}} + If you aren't sure where to add yourself, add yourself to `sig-docs-en-reviews`. + {{< /note >}} + +1. Assign the PR to one or more SIG-Docs approvers (usernames listed under + `sig-docs-{language}-owners`). + +If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, +[K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) +assigns and suggests you as a reviewer on new pull requests. + +## Approvers + +Approvers review and approve pull requests for merging. Approvers are members of the +[@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs) +GitHub teams. + +Approvers can do the following: + +- Everything listed under [Anyone](#anyone), [Members](#members) and [Reviewers](#reviewers) +- Publish contributor content by approving and merging pull requests using the `/approve` comment +- Propose improvements to the style guide +- Propose improvements to docs tests +- Propose improvements to the Kubernetes website or other tooling + +If the PR already has a `/lgtm`, or if the approver also comments with +`/lgtm`, the PR merges automatically. A SIG Docs approver should only leave a +`/lgtm` on a change that doesn't need additional technical review. + + +### Approving pull requests + +Approvers and SIG Docs leads are the only ones who can merge pull requests +into the website repository. This comes with certain responsibilities. + +- Approvers can use the `/approve` command, which merges PRs into the repo. + + {{< warning >}} + A careless merge can break the site, so be sure that when you merge something, you mean it. + {{< /warning >}} + +- Make sure that proposed changes meet the + [documentation content guide](/docs/contribute/style/content-guide/). + + If you ever have a question, or you're not sure about something, feel free + to call for additional review. + +- Verify that Netlify tests pass before you `/approve` a PR. + + Netlify tests must pass before approving + +- Visit the Netlify page preview for a PR to make sure things look good before approving. + +- Participate in the + [PR Wrangler rotation schedule](https://github.com/kubernetes/website/wiki/PR-Wranglers) + for weekly rotations. SIG Docs expects all approvers to participate in this + rotation. See [PR wranglers](/docs/contribute/participate/pr-wranglers/). + for more details. + +### Becoming an approver + +When you meet the +[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#approver), +you can become a SIG Docs approver. Approvers in other SIGs must apply +separately for approver status in SIG Docs. + +To apply: + +1. Open a pull request adding yourself to a section of the + [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) + file in the `kubernetes/website` repository. + + {{< note >}} + If you aren't sure where to add yourself, add yourself to `sig-docs-en-owners`. + {{< /note >}} + +2. Assign the PR to one or more current SIG Docs approvers. + +If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, +[@k8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) +assigns and suggests you as a reviewer on new pull requests. + +## {{% heading "whatsnext" %}} + +- Read about [PR wrangling](/docs/contribute/participate/pr-wranglers/), a role all approvers take on rotation. diff --git a/content/en/docs/Contribute/style/_index.md b/content/en/docs/Contribute/style/_index.md new file mode 100644 index 000000000000..d3633b5aaae5 --- /dev/null +++ b/content/en/docs/Contribute/style/_index.md @@ -0,0 +1,7 @@ +--- +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 new file mode 100644 index 000000000000..1bc311fc1f4c --- /dev/null +++ b/content/en/docs/Contribute/style/content-guide.md @@ -0,0 +1,74 @@ +--- +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 new file mode 100644 index 000000000000..351f48fe339d --- /dev/null +++ b/content/en/docs/Contribute/style/content-organization.md @@ -0,0 +1,147 @@ +--- +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 new file mode 100644 index 000000000000..6a0d44828f5a --- /dev/null +++ b/content/en/docs/Contribute/style/diagram-guide.md @@ -0,0 +1,780 @@ +--- +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 new file mode 100644 index 000000000000..9e9f45b0a604 --- /dev/null +++ b/content/en/docs/Contribute/style/hugo-shortcodes/example1.md @@ -0,0 +1,9 @@ +--- +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 new file mode 100644 index 000000000000..bf03fb5d93d6 --- /dev/null +++ b/content/en/docs/Contribute/style/hugo-shortcodes/example2.md @@ -0,0 +1,7 @@ +--- +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 new file mode 100644 index 000000000000..2c8c10309e8a --- /dev/null +++ b/content/en/docs/Contribute/style/hugo-shortcodes/index.md @@ -0,0 +1,410 @@ +--- +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 new file mode 100644 index 000000000000..bd4327414a10 --- /dev/null +++ b/content/en/docs/Contribute/style/hugo-shortcodes/podtemplate.json @@ -0,0 +1,22 @@ + { + "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 new file mode 100644 index 000000000000..ada2274d9974 --- /dev/null +++ b/content/en/docs/Contribute/style/page-content-types.md @@ -0,0 +1,218 @@ +--- +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/style-guide.md b/content/en/docs/Contribute/style/style-guide.md new file mode 100644 index 000000000000..b6a881987902 --- /dev/null +++ b/content/en/docs/Contribute/style/style-guide.md @@ -0,0 +1,674 @@ +--- +title: Documentation Style Guide +linktitle: Style guide +content_type: concept +weight: 40 +--- + + +This page gives writing style guidelines for the Kubernetes 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 +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 +or addition, [add it to the agenda](https://bit.ly/sig-docs-agenda) for an upcoming +SIG Docs meeting, and attend the meeting to participate in the discussion. + + + +{{< note >}} +Kubernetes 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 +glossary entries, tabs, and representing feature state. +{{< /note >}} + +## Language + +Kubernetes documentation has been translated into multiple languages +(see [Localization READMEs](https://github.com/kubernetes/website/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 English-language documentation uses U.S. English spelling and grammar. + +{{< comment >}}[If you're localizing this page, you can omit the point about US English.]{{< /comment >}} + +## Documentation formatting standards + +### Use upper camel case for API objects + +When you refer specifically to interacting with an API object, use +[UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), also known as +Pascal case. You may see different capitalization, such as "configMap", +in the [API Reference](/docs/reference/kubernetes-api/). When writing +general documentation, it's better to use upper camel case, calling it "ConfigMap" instead. + +When you are generally discussing an API object, use +[sentence-style capitalization](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization). + +The following examples focus on capitalization. For more information about formatting +API object names, review the related guidance on [Code Style](#code-style-inline-code). + +{{< table caption = "Do and Don't - Use Pascal case for API objects" >}} +Do | Don't +:--| :----- +The HorizontalPodAutoscaler resource is responsible for ... | The Horizontal pod autoscaler is responsible for ... +A PodList object is a list of pods. | A Pod List object is a list of pods. +The Volume object contains a `hostPath` field. | The volume object contains a hostPath field. +Every ConfigMap object is part of a namespace. | Every configMap object is part of a namespace. +For managing confidential data, consider using the Secret API. | For managing confidential data, consider using the secret API. +{{< /table >}} + +### Use angle brackets for placeholders + +Use angle brackets for placeholders. Tell the reader what a placeholder +represents, for example: + +Display information about a pod: + +```shell +kubectl describe pod -n +``` + +If the namespace of the pod is `default`, you can omit the '-n' parameter. + +### Use bold for user interface elements + +{{< table caption = "Do and Don't - Bold interface elements" >}} +Do | Don't +:--| :----- +Click **Fork**. | Click "Fork". +Select **Other**. | Select "Other". +{{< /table >}} + +### Use italics to define or introduce new terms + +{{< table caption = "Do and Don't - Use italics for new terms" >}} +Do | Don't +:--| :----- +A _cluster_ is a set of nodes ... | A "cluster" is a set of nodes ... +These components form the _control plane_. | These components form the **control plane**. +{{< /table >}} + +### Use code style for filenames, directories, and paths + +{{< table caption = "Do and Don't - Use code style for filenames, directories, and paths" >}} +Do | Don't +:--| :----- +Open the `envars.yaml` file. | Open the envars.yaml file. +Go to the `/docs/tutorials` directory. | Go to the /docs/tutorials directory. +Open the `/_data/concepts.yaml` file. | Open the /\_data/concepts.yaml file. +{{< /table >}} + +### Use the international standard for punctuation inside quotes + +{{< table caption = "Do and Don't - Use the international standard for punctuation inside quotes" >}} +Do | Don't +:--| :----- +events are recorded with an associated "stage". | events are recorded with an associated "stage." +The copy is called a "fork". | The copy is called a "fork." +{{< /table >}} + +## Inline code formatting + +### Use code style for inline code, commands, and API objects {#code-style-inline-code} + +For inline code in an HTML document, use the `` tag. In a Markdown +document, use the backtick (`` ` ``). + +{{< table caption = "Do and Don't - Use code style for inline code, commands, and API objects" >}} +Do | Don't +:--| :----- +The `kubectl run` command creates a `Pod`. | The "kubectl run" command creates a pod. +The kubelet on each node acquires a `Lease`… | The kubelet on each node acquires a lease… +A `PersistentVolume` represents durable storage… | A Persistent Volume represents durable storage… +For declarative management, use `kubectl apply`. | For declarative management, use "kubectl apply". +Enclose code samples with triple backticks. (\`\`\`)| Enclose code samples with any other syntax. +Use single backticks to enclose inline code. For example, `var example = true`. | Use two asterisks (`**`) or an underscore (`_`) to enclose inline code. For example, **var example = true**. +Use triple backticks before and after a multi-line block of code for fenced code blocks. | Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations. +Use meaningful variable names that have a context. | Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context. +Remove trailing spaces in the code. | Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well. +{{< /table >}} + +{{< note >}} +The website supports syntax highlighting for code samples, but specifying a language +is optional. Syntax highlighting in the code block should conform to the +[contrast guidelines.](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0&showtechniques=141%2C143#contrast-minimum) +{{< /note >}} + +### Use code style for object field names and namespaces + +{{< table caption = "Do and Don't - Use code style for object field names" >}} +Do | Don't +:--| :----- +Set the value of the `replicas` field in the configuration file. | Set the value of the "replicas" field in the configuration file. +The value of the `exec` field is an ExecAction object. | The value of the "exec" field is an ExecAction object. +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 + +{{< table caption = "Do and Don't - Use code style for Kubernetes command tool and component names" >}} +Do | Don't +:--| :----- +The kubelet preserves node stability. | The `kubelet` preserves node stability. +The `kubectl` handles locating and authenticating to the API server. | The kubectl handles locating and authenticating to the apiserver. +Run the process with the certificate, `kube-apiserver --client-ca-file=FILENAME`. | Run the process with the certificate, kube-apiserver --client-ca-file=FILENAME. | +{{< /table >}} + +### Starting a sentence with a component tool or component name + +{{< table caption = "Do and Don't - Starting a sentence with a component tool or component name" >}} +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. +{{< /table >}} + +### Use a general descriptor over a component name + +{{< 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. +Aggregated APIs are subordinate API servers. | Aggregated APIs are subordinate APIServers. +{{< /table >}} + +### Use normal style for string and integer field values + +For field values of type string or integer, use normal style without quotation marks. + +{{< table caption = "Do and Don't - Use normal style for string and integer field values" >}} +Do | Don't +:--| :----- +Set the value of `imagePullPolicy` to Always. | Set the value of `imagePullPolicy` to "Always". +Set the value of `image` to nginx:1.16. | Set the value of `image` to `nginx:1.16`. +Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`. +{{< /table >}} + +## Referring to Kubernetes 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`, +`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 + +The different Kubernetes 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. + +Always use "resource" or "object" when referring to an API resource in docs. +For example, use "a `Secret` object" over just "a `Secret`". + +### API resource names + +Always format API resource names using [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), +also known as PascalCase, and code formatting. + +For inline code in an HTML document, use the `` tag. In a Markdown document, use the backtick (`` ` ``). + +Don't split an API object name into separate words. For example, use `PodTemplateList`, not Pod Template List. + +For more information about PascalCase and code formatting, please review the related guidance on +[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). + +## Code snippet formatting + +### Don't include the command prompt + +{{< table caption = "Do and Don't - Don't include the command prompt" >}} +Do | Don't +:--| :----- +kubectl get pods | $ kubectl get pods +{{< /table >}} + +### Separate commands from output + +Verify that the pod is running on your chosen node: + +```shell +kubectl get pods --output=wide +``` + +The output is similar to this: + +```console +NAME READY STATUS RESTARTS AGE IP NODE +nginx 1/1 Running 0 13s 10.200.0.4 worker0 +``` + +### Versioning Kubernetes 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 +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 +`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, +the front-matter of your markdown file should look something like: + +```yaml +--- +title: +min-kubernetes-server-version: v1.8 +--- +``` + +In code and configuration examples, do not include comments about alternative versions. +Be careful to not include incorrect statements in your examples as comments, such as: + +```yaml +apiVersion: v1 # earlier versions use... +kind: Pod +... +``` + +## Kubernetes.io word list + +A list of Kubernetes-specific terms and words to be used consistently across the site. + +{{< table caption = "Kubernetes.io word list" >}} +Term | Usage +:--- | :---- +Kubernetes | Kubernetes 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. +{{< /table >}} + +## Shortcodes + +Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create +different rhetorical appeal levels. Our documentation supports three different +shortcodes in this category: **Note** `{{}}`, +**Caution** `{{}}`, and **Warning** `{{}}`. + +1. Surround the text with an opening and closing shortcode. + +2. Use the following syntax to apply a style: + + ```none + {{}} + No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.) + {{}} + ``` + + The output is: + + {{< note >}} + The prefix you choose is the same text for the tag. + {{< /note >}} + +### Note + +Use `{{}}` to highlight a tip or a piece of information that may be helpful to know. + +For example: + +``` +{{}} +You can _still_ use Markdown inside these callouts. +{{}} +``` + +The output is: + +{{< note >}} +You can _still_ use Markdown inside these callouts. +{{< /note >}} + +You can use a `{{}}` in a list: + +``` +1. Use the note shortcode in a list + +1. A second item with an embedded note + + {{}} + Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues). + {{}} + +1. A third item in a list + +1. A fourth item in a list +``` + +The output is: + +1. Use the note shortcode in a list + +1. A second item with an embedded note + + {{< note >}} + Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues). + {{< /note >}} + +1. A third item in a list + +1. A fourth item in a list + +### Caution + +Use `{{}}` to call attention to an important piece of information to avoid pitfalls. + +For example: + +``` +{{}} +The callout style only applies to the line directly above the tag. +{{}} +``` + +The output is: + +{{< caution >}} +The callout style only applies to the line directly above the tag. +{{< /caution >}} + +### Warning + +Use `{{}}` to indicate danger or a piece of information that is crucial to follow. + +For example: + +``` +{{}} +Beware. +{{}} +``` + +The output is: + +{{< warning >}} +Beware. +{{< /warning >}} + +## Common Shortcode Issues + +### Ordered Lists + +Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag. + +For example: + + 1. Preheat oven to 350˚F + + 1. Prepare the batter, and pour into springform pan. + {{}}Grease the pan for best results.{{}} + + 1. Bake for 20-25 minutes or until set. + +The output is: + +1. Preheat oven to 350˚F + +1. Prepare the batter, and pour into springform pan. + + {{< note >}}Grease the pan for best results.{{< /note >}} + +1. Bake for 20-25 minutes or until set. + +### Include Statements + +Shortcodes inside include statements will break the build. You must insert them +in the parent document, before and after you call the include. For example: + +``` +{{}} +{{}} +{{}} +``` + +## Markdown elements + +### Line breaks + +Use a single newline to separate block-level content like headings, lists, images, +code blocks, and others. The exception is second-level headings, where it should +be two newlines. Second-level headings follow the first-level (or the title) without +any preceding paragraphs or texts. A two line spacing helps visualize the overall +structure of content in a code editor better. + +Manually wrap paragraphs in the Markdown source when appropriate. Since the git +tool and the GitHub website generate file diffs on a line-by-line basis, +manually wrapping long lines helps the reviewers to easily find out the changes +made in a PR and provide feedback. It also helps the downstream localization +teams where people track the upstream changes on a per-line basis. Line +wrapping can happen at the end of a sentence or a punctuation character, for +example. One exception to this is that a Markdown link or a shortcode is +expected to be in a single line. + +### Headings and titles {#headings} + +People accessing this documentation may use a screen reader or other assistive technology (AT). +[Screen readers](https://en.wikipedia.org/wiki/Screen_reader) are linear output devices, +they output items on a page one at a time. If there is a lot of content on a page, you can +use headings to give the page an internal structure. A good page structure helps all readers +to easily navigate the page or filter topics of interest. + +{{< table caption = "Do and Don't - Headings" >}} +Do | Don't +:--| :----- +Update the title in the front matter of the page or blog post. | Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading. +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` +{{< /table >}} + +### Paragraphs + +{{< table caption = "Do and Don't - Paragraphs" >}} +Do | Don't +:--| :----- +Try to keep paragraphs under 6 sentences. | Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it. +Use three hyphens (`---`) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section. | Use horizontal rules for decoration. +{{< /table >}} + +### Links + +{{< table caption = "Do and Don't - Links" >}} +Do | Don't +:--| :----- +Write hyperlinks that give you context for the content they link to. For example: Certain ports are open on your machines. See Check required ports for more details. | Use ambiguous terms such as "click here". For example: Certain ports are open on your machines. See here for more details. +Write Markdown-style links: `[link text](URL)`. For example: `[Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions)` and the output is [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions). | Write HTML-style links: `Visit our tutorial!`, or create links that open in new tabs or windows. For example: `[example website](https://example.com){target="_blank"}` +{{< /table >}} + +### Lists + +Group items in a list that are related to each other and need to appear in a specific +order or to indicate a correlation between multiple items. When a screen reader comes +across a list—whether it is an ordered or unordered list—it will be announced to the +user that there is a group of list items. The user can then use the arrow keys to move +up and down between the various items in the list. Website navigation links can also be +marked up as list items; after all they are nothing but a group of related links. + +- End each item in a list with a period if one or more items in the list are complete + sentences. For the sake of consistency, normally either all items or none should be complete sentences. + + {{< note >}} + Ordered lists that are part of an incomplete introductory sentence can be in lowercase + and punctuated as if each item was a part of the introductory sentence. + {{< /note >}} + +- Use the number one (`1.`) for ordered lists. + +- Use (`+`), (`*`), or (`-`) for unordered lists. + +- Leave a blank line after each list. + +- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅). + +- List items may consist of multiple paragraphs. Each subsequent paragraph in a list + item must be indented by either four spaces or one tab. + +### Tables + +The semantic purpose of a data table is to present tabular data. Sighted users can +quickly scan the table but a screen reader goes through line by line. A table caption +is used to create a descriptive title for a data table. Assistive technologies (AT) +use the HTML table caption element to identify the table contents to the user within the page structure. + +- Add table captions using [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions) for tables. + +## Content best practices + +This section contains suggested best practices for clear, concise, and consistent content. + +### Use present tense + +{{< table caption = "Do and Don't - Use present tense" >}} +Do | Don't +:--| :----- +This command starts a proxy. | This command will start a proxy. + {{< /table >}} + +Exception: Use future or past tense if it is required to convey the correct +meaning. + +### Use active voice + +{{< table caption = "Do and Don't - Use active voice" >}} +Do | Don't +:--| :----- +You can explore the API using a browser. | The API can be explored using a browser. +The YAML file specifies the replica count. | The replica count is specified in the YAML file. +{{< /table >}} + +Exception: Use passive voice if active voice leads to an awkward construction. + +### Use simple and direct language + +Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." + +{{< table caption = "Do and Don't - Use simple and direct language" >}} +Do | Don't +:--| :----- +To create a ReplicaSet, ... | In order to create a ReplicaSet, ... +See the configuration file. | Please see the configuration file. +View the pods. | With this next command, we'll view the pods. +{{< /table >}} + +### Address the reader as "you" + +{{< table caption = "Do and Don't - Addressing the reader" >}} +Do | Don't +:--| :----- +You can create a Deployment by ... | We'll create a Deployment by ... +In the preceding output, you can see... | In the preceding output, we can see ... +{{< /table >}} + +### Avoid Latin phrases + +Prefer English terms over Latin abbreviations. + +{{< table caption = "Do and Don't - Avoid Latin phrases" >}} +Do | Don't +:--| :----- +For example, ... | e.g., ... +That is, ...| i.e., ... +{{< /table >}} + +Exception: Use "etc." for et cetera. + +## Patterns to avoid + +### Avoid using "we" + +Using "we" in a sentence can be confusing, because the reader might not know +whether they're part of the "we" you're describing. + +{{< table caption = "Do and Don't - Patterns to avoid" >}} +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 ... +This page teaches you how to use pods. | In this page, we are going to learn about pods. +{{< /table >}} + +### Avoid jargon and idioms + +Some readers speak English as a second language. Avoid jargon and idioms to help them understand better. + +{{< table caption = "Do and Don't - Avoid jargon and idioms" >}} +Do | Don't +:--| :----- +Internally, ... | Under the hood, ... +Create a new cluster. | Turn up a new cluster. +{{< /table >}} + +### Avoid statements about the future + +Avoid making promises or giving hints about the future. If you need to talk about +an alpha feature, put the text under a heading that identifies it as alpha +information. + +An exception to this rule is documentation about announced deprecations +targeting removal in future versions. One example of documentation like this +is the [Deprecated API migration guide](/docs/reference/using-api/deprecation-guide/). + +### Avoid statements that will soon be out of date + +Avoid words like "currently" and "new." A feature that is new today might not be +considered new in a few months. + +{{< table caption = "Do and Don't - Avoid statements that will soon be out of date" >}} +Do | Don't +:--| :----- +In version 1.4, ... | In the current version, ... +The Federation feature provides ... | The new Federation feature provides ... +{{< /table >}} + +### Avoid words that assume a specific level of understanding + +Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value. + +{{< table caption = "Do and Don't - Avoid insensitive words" >}} +Do | Don't +:--| :----- +Include one command in ... | Include just one command in ... +Run the container ... | Simply run the container ... +You can remove ... | You can easily remove ... +These steps ... | These simple steps ... +{{< /table >}} + +### EditorConfig file +The Kubernetes 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. + +## {{% heading "whatsnext" %}} + +* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/). +* Learn about [using page templates](/docs/contribute/style/page-content-types/). +* Learn about [custom hugo shortcodes](/docs/contribute/style/hugo-shortcodes/). +* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/). diff --git a/content/en/docs/Contribute/style/write-new-topic.md b/content/en/docs/Contribute/style/write-new-topic.md new file mode 100644 index 000000000000..4204e937dda1 --- /dev/null +++ b/content/en/docs/Contribute/style/write-new-topic.md @@ -0,0 +1,170 @@ +--- +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/). + diff --git a/content/en/docs/Contribute/suggesting-improvements.md b/content/en/docs/Contribute/suggesting-improvements.md new file mode 100644 index 000000000000..aac6ce1c1351 --- /dev/null +++ b/content/en/docs/Contribute/suggesting-improvements.md @@ -0,0 +1,67 @@ +--- +title: Suggesting content improvements +content_type: concept +weight: 10 +card: + name: contribute + weight: 15 + anchors: + - anchor: "#opening-an-issue" + title: Suggest content improvements +--- + + + +If you notice an issue with Kubernetes documentation or have an idea for new content, then open an issue. All you need is a [GitHub account](https://github.com/join) and a web browser. + +In most cases, new work on Kubernetes documentation begins with an issue in GitHub. Kubernetes contributors +then review, categorize and tag issues as needed. Next, you or another member +of the Kubernetes community open a pull request with changes to resolve the issue. + + + + + +## Opening an issue + +If you want to suggest improvements to existing content or notice an error, then open an issue. + +1. Click the **Create an issue** link on the right sidebar. This redirects you + to a GitHub issue page pre-populated with some headers. +2. Describe the issue or suggestion for improvement. Provide as many details as you can. +3. Click **Submit new issue**. + +After submitting, check in on your issue occasionally or turn on GitHub notifications. +Reviewers and other community members might ask questions before +they can take action on your issue. + +## Suggesting new content + +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 an issue**. +- Go to [GitHub](https://github.com/kubernetes/website/issues/new/) and file the issue directly. + +## How to file great issues + + +Keep the following in mind when filing an issue: + +- Provide a clear issue description. Describe what specifically is missing, out of date, + wrong, or needs improvement. +- Explain the specific impact the issue has on users. +- Limit the scope of a given issue to a reasonable unit of work. For problems + with a large scope, break them down into smaller issues. For example, "Fix the security docs" + is too broad, but "Add details to the 'Restricting network access' topic" is specific enough + to be actionable. +- Search the existing issues to see if there's anything related or similar to the + new issue. +- If the new issue relates to another issue or pull request, refer to it + either by its full URL or by the issue or pull request number prefixed + with a `#` character. For example, `Introduced by #987654`. +- Follow the [Code of Conduct](/community/code-of-conduct/). Respect your +fellow contributors. For example, "The docs are terrible" is not + helpful or polite feedback. + + From 000105f657665fbb56db77c9c8a94e2ce7834353 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 12:59:24 +0100 Subject: [PATCH 03/62] Main contribution guide --- content/en/docs/Contribute/_index.md | 484 +++++++++++++- .../{new-content => }/blogs-case-studies.md | 0 .../Contribute/new-content/new-features.md | 143 ---- .../docs/Contribute/new-content/open-a-pr.md | 628 ------------------ .../Contribute/roles-and-responsibilities.md | 237 ------- .../Contribute/suggesting-improvements.md | 67 -- 6 files changed, 476 insertions(+), 1083 deletions(-) rename content/en/docs/Contribute/{new-content => }/blogs-case-studies.md (100%) delete mode 100644 content/en/docs/Contribute/new-content/new-features.md delete mode 100644 content/en/docs/Contribute/new-content/open-a-pr.md delete mode 100644 content/en/docs/Contribute/roles-and-responsibilities.md delete mode 100644 content/en/docs/Contribute/suggesting-improvements.md diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 851cc0199d80..b80faf030304 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -5,8 +5,9 @@ weight: 200 cSpell:ignore: --- -This website is maintained by -[OpenTelemetry SIG Comms](/docs/contribute/#get-involved-with-sig-comms). +You can open an issue about OpenTelemetry documentation, or contribute a change +with a pull request (PR) to the +[`open-telemetry/opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). OpenTelemetry documentation contributors: @@ -20,17 +21,13 @@ See also the general , which provides details on the Contributor License Agreement and the Code of Conduct. -## Get started - -You can open an issue about OpenTelemetry documentation, or contribute a change -with a pull request (PR) to the -[`open-telemetry/opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). +## Requirements To contribute, you need to be familiar with the following techs and tools: * [git](https://git-scm.com/) * [GitHub](https://lab.github.com/) -* Markdown +* Markdown (CommonMark) * YAML For technical details concerning how the documentation is built and tested @@ -38,6 +35,477 @@ locally, see the [CONTRIBUTING.md](https://github.com/open-telemetry/opentelemetry.io/blob/main/CONTRIBUTING.md) file. +### Sign the CNCF CLA {#sign-the-cla} + +All OpenTelemetry contributors must read the +[Contributor guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) +and +[sign the Contributor License Agreement (CLA)](https://docs.linuxfoundation.org/lfx/easycla/contributors) +. + +Pull requests from contributors who haven't signed the CLA fail the automated +tests. The name and email you provide must match those found in +your `git config`, and your git name and email must match those used for the +CNCF CLA. + +## Contribute new content + +{{< mermaid >}} +flowchart LR + subgraph first[How to contribute] + direction TB + T[ ] -.- + A[Sign the CNCF CLA] --> D[Write docs in markdown
and build site with Hugo] + D[Write docs in markdown
and build site with Hugo] --- E[Push source to GitHub] + E --- G[Open a pull request] + end + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,B,C,D,E,F,G,H grey +class S,T spacewhite +class first,second white +{{}} + +***Figure - Contributing new content*** + +The previous figure presents the basic steps for new docs contributions. + +To contribute new content pages or improve existing content pages, open a pull +request (PR): + +- If your change is small, or you're unfamiliar with Git, read +[Changes using GitHub](#changes-using-github) to learn how to edit a page. +- If your changes are large, read [Work from a local fork](#fork-the-repo) to learn how to make +changes locally on your computer. + +### Changes using GitHub {#changes-using-github} + +If you're less experienced with Git workflows, here's an easier method of +opening a pull request. Figure 1 outlines the steps and the details follow. + +{{< mermaid >}} +flowchart LR +A([fa:fa-user New
Contributor]) --- id1[(open-telemetry/opentelemetry.io
GitHub)] +subgraph tasks[Changes using GitHub] +direction TB + 0[ ] -.- + 1[1. Edit this page] --> 2[2. Use GitHub markdown
editor to make changes] + 2 --> 3[3. fill in Propose file change] + +end +subgraph tasks2[ ] +direction TB +4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] +6 --> 7[7. select Create pull request] +end + +id1 --> tasks --> tasks2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,1,2,3,4,5,6,7 grey +class 0 spacewhite +class tasks,tasks2 white +class id1 k8s +{{}} + +Figure 1. Steps for opening a PR using GitHub. + +1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. + +1. Make your changes in the GitHub editor. + +1. Below the editor, fill in the **Propose file change** form. + +1. Select **Propose file change**. + +1. Select **Create pull request**. + +1. The **Open a pull request** screen appears. Your description helps reviewers understand your change. + +1. Select **Create pull request**. + +Before merging a pull request, OpenTelemetry community members review and +approve it. If you have someone in mind, leave a comment with their GitHub +username in it. + +If a reviewer asks you to make changes: + +1. Go to the **Files changed** tab. +1. Select the pencil (edit) icon on any files changed by the pull request. +1. Make the changes requested. +1. Commit the changes. + +When your review is complete, a reviewer merges your PR and your changes go liv +a few minutes later. + +### Work from a local fork {#fork-the-repo} + +If you're more experienced with Git, or if your changes are larger than a few +lines, work from a local fork. + +Make sure you have +[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed +on your computer. You can also use a user interface for Git. + +Figure 2 shows the steps to follow when you work from a local fork. The details +for each step follow. + +{{< mermaid >}} +flowchart LR +1[Fork the open-telemetry/opentelemetry
repository] --> 2[Create local clone
and set upstream] +subgraph changes[Your changes] +direction TB +S[ ] -.- +3[Create a branch
example: my_new_branch] --> 3a[Make changes using
a text editor] --> 4["Preview your changes
locally using Hugo
(localhost:1313)"] +end +subgraph changes2[Commit / Push] +direction TB +T[ ] -.- +5[Commit your changes] --> 6[Push commit to
origin/my_new_branch] +end + +2 --> changes --> changes2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class 1,2,3,3a,4,5,6 grey +class S,T spacewhite +class changes,changes2 white +{{}} + +Figure 2. Working from a local fork to make your changes. + +#### Fork the kubernetes/website repository + +1. Navigate to the [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) repository. +1. Select **Fork**. + +#### Create a local clone and set the upstream + +1. In a terminal window, clone your fork and install the requirements: + + ```shell + git clone git@github.com:/opentelemetry.io.git + cd opentelemetry.io + npm install + ``` + +1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream` remote: + + ```shell + git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git + ``` + +1. Confirm your `origin` and `upstream` repositories: + + ```shell + git remote -v + ``` + + Output is similar to: + + ```none + origin git@github.com:/opentelemetry.io.git (fetch) + origin git@github.com:/opentelemetry.io.git (push) + upstream https://github.com/open-telemetry/opentelemetry.io.git (fetch) + upstream https://github.com/open-telemetry/opentelemetry.io.git (push) + ``` + +1. Fetch commits from your fork's `origin/main` and `open-telemetry/opentelemetry.io`'s `upstream/main`: + + ```shell + git fetch origin + git fetch upstream + ``` + + This makes sure your local repository is up to date before you start making changes. + +#### Create a branch + +1. Create a new branch. This example assumes the base branch is `upstream/main`: + + ```shell + git checkout -b upstream/main + ``` + +1. Make your changes using a code or text editor. + +At any time, use the `git status` command to see what files you've changed. + +#### Commit your changes + +When you are ready to submit a pull request, commit your changes. + +1. In your local repository, check which files you need to commit: + + ```shell + git status + ``` + + Output is similar to: + + ```none + On branch + Your branch is up to date with 'origin/'. + + Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: content/en/docs/contribute/new-content/contributing-content.md + + no changes added to commit (use "git add" and/or "git commit -a") + ``` + +1. Add the files listed under **Changes not staged for commit** to the commit: + + ```shell + git add + ``` + + Repeat this for each file. + +1. After adding all the files, create a commit: + + ```shell + git commit -m "Your commit message" + ``` + +1. Push your local branch and its new commit to your remote fork: + + ```shell + git push origin + ``` + +#### Preview your changes locally {#preview-locally} + +Preview your changes locally before pushing them or opening a pull request. +A preview lets you catch build errors or markdown formatting problems. + +To build and serve the site locally with Hugo, run the following command: + +```shell +npm run serve +``` + +Navigate to `https://localhost:1313` in your web browser to see the local +preview. Hugo watches the changes and rebuilds the site as needed. + +To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or +close the terminal window. + +#### Open a pull request from your fork {#open-a-pr} + +Figure 3 shows the steps to open a PR from your fork to the +[open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) +. + +{{< mermaid >}} +flowchart LR +subgraph first[ ] +direction TB +1[1. Go to open-telemetry/opentelemetry.io repository] --> 2[2. Select New Pull Request] +2 --> 3[3. Select compare across forks] +3 --> 4[4. Select your fork from
head repository drop-down menu] +end +subgraph second [ ] +direction TB +5[5. Select your branch from
the compare drop-down menu] --> 6[6. Select Create Pull Request] +6 --> 7[7. Add a description
to your PR] +7 --> 8[8. Select Create pull request] +end + +first --> second + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +class 1,2,3,4,5,6,7,8 grey +class first,second white +{{}} + +Figure 3. Steps to open a PR from your fork to the +[open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). + +1. In a web browser, go to the [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) repository. +1. Select **New Pull Request**. +1. Select **compare across forks**. +1. From the **head repository** drop-down menu, select your fork. +1. From the **compare** drop-down menu, select your branch. +1. Select **Create Pull Request**. +1. Add a description for your pull request: + + - **Title** (50 characters or less): Summarize the intent of the change. + - **Description**: Describe the change in more detail. + + - If there is a related GitHub issue, include `Fixes #12345` or `Closes #12345` in the + description. GitHub's automation closes the mentioned issue after merging the PR if used. + If there are other related PRs, link those as well. + - If you want advice on something specific, include any questions you'd like reviewers to + think about in your description. + +1. Select the **Create pull request** button. + +Your pull request is available in +[Pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls). + +After opening a PR, GitHub runs automated tests and tries to deploy a preview using +[Netlify](https://www.netlify.com/). + +- If the Netlify build fails, select **Details** for more information. +- If the Netlify build succeeds, select **Details** opens a staged version of the OpenTelemetry + website with your changes applied. This is how reviewers check your changes. + +GitHub also automatically assigns labels to a PR to help reviewers. + +#### Changes from reviewers + +Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits. + +1. Fetch commits from your remote fork and rebase your working branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + +1. After rebasing, force-push new changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +#### Merge conflicts and rebasing + +If another contributor commits changes to the same file in another PR, it can +create a merge conflict. You must resolve all merge conflicts in your PR. + +1. Update your fork and rebase your local branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + + Then force-push the changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and rebase your branch: + + ```shell + git fetch upstream + git rebase upstream/main + ``` + +1. Inspect the results of the rebase: + + ```shell + git status + ``` + + This results in a number of files marked as conflicted. + +1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. + Resolve the conflict and delete the conflict marker. + + {{< note >}} + For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). + {{< /note >}} + +1. Add the files to the changeset: + + ```shell + git add + ``` + +1. Continue the rebase: + + ```shell + git rebase --continue + ``` + +1. Repeat steps 2 to 5 as needed. + + After applying all commits, the `git status` command shows that the rebase is complete. + +1. Force-push the branch to your fork: + + ```shell + git push --force-with-lease origin + ``` + + The pull request no longer shows any conflicts. + +## Contribute to other repos + +The [Kubernetes 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. + +If you see text you'd like to improve, use GitHub to search all repositories in +the OpenTelemetry organization. This can help you figure out where to submit +your issue or PR. + +Each repository has its own processes and procedures. Before you file an issue +or submit a PR, read that repository's `README.md`, `CONTRIBUTING.md`, and +`code-of-conduct.md`, if they exist. + +Most repositories use issue and PR templates. Have a look through some open +issues and PRs to get a feel for that team's processes. Make sure to fill out +the templates with as much detail as possible when you file issues or PRs. + +## Open an issue + +If you want to suggest improvements to existing content or notice an error, +open an issue. + +1. Click the **Create documentation issue** link on the right sidebar. This redirects you + to a GitHub issue page prepopulated with some headers. +2. Describe the issue or suggestion for improvement. Provide as many details as you can. +3. Click **Submit new issue**. + +After submitting, check in on your issue occasionally or turn on GitHub +notifications. Reviewers and other community members might ask questions before +they can take action on your issue. + +### Suggesting new content + +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. + +## How to file great issues + +Keep the following in mind when filing an issue: + +- Provide a clear issue description. Describe what specifically is missing, out of date, + wrong, or needs improvement. +- Explain the specific impact the issue has on users. +- Limit the scope of a given issue to a reasonable unit of work. For problems + with a large scope, break them down into smaller issues. For example, "Fix the security docs" + is too broad, but "Add details to the 'Restricting network access' topic" is specific enough + to be actionable. +- Search the existing issues to see if there's anything related or similar to the + new issue. +- If the new issue relates to another issue or pull request, refer to it + either by its full URL or by the issue or pull request number prefixed + with a `#` character. For example, `Introduced by #987654`. +- Follow the [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). Respect your +fellow contributors. For example, "The docs are terrible" is not + helpful or polite feedback. + + ## Other ways to contribute - Visit the [OpenTelemetry community site](/community/). diff --git a/content/en/docs/Contribute/new-content/blogs-case-studies.md b/content/en/docs/Contribute/blogs-case-studies.md similarity index 100% rename from content/en/docs/Contribute/new-content/blogs-case-studies.md rename to content/en/docs/Contribute/blogs-case-studies.md diff --git a/content/en/docs/Contribute/new-content/new-features.md b/content/en/docs/Contribute/new-content/new-features.md deleted file mode 100644 index 3b71e2d5316d..000000000000 --- a/content/en/docs/Contribute/new-content/new-features.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Documenting a feature for a release -linktitle: Documenting for a release -content_type: concept -main_menu: true -weight: 20 -card: - name: contribute - weight: 45 - title: Documenting a feature for a release ---- - - -Each major Kubernetes release introduces new features that require documentation. New releases also bring updates to existing features and documentation (such as upgrading a feature from alpha to beta). - -Generally, the SIG responsible for a feature submits draft documentation of the -feature as a pull request to the appropriate development branch of the -`kubernetes/website` repository, and someone on the SIG Docs team provides -editorial feedback or edits the draft directly. This section covers the branching -conventions and process used during a release by both groups. - - - - - -## For documentation contributors - -In general, documentation contributors don't write content from scratch for a release. -Instead, they work with the SIG creating a new feature to refine the draft documentation and make it release ready. - -After you've chosen a feature to document or assist, ask about it in the `#sig-docs` -Slack channel, in a weekly SIG Docs meeting, or directly on the PR filed by the -feature SIG. If you're given the go-ahead, you can edit into the PR using one of -the techniques described in -[Commit into another person's PR](/docs/contribute/review/for-approvers/#commit-into-another-person-s-pr). - -### Find out about upcoming features - -To find out about upcoming features, attend the weekly SIG Release meeting (see -the [community](/community/) page for upcoming meetings) -and monitor the release-specific documentation -in the [kubernetes/sig-release](https://github.com/kubernetes/sig-release/) -repository. Each release has a sub-directory in the [/sig-release/tree/master/releases/](https://github.com/kubernetes/sig-release/tree/master/releases) -directory. The sub-directory contains a release schedule, a draft of the release -notes, and a document listing each person on the release team. - -The release schedule contains links to all other documents, meetings, -meeting minutes, and milestones relating to the release. It also contains -information about the goals and timeline of the release, and any special -processes in place for this release. Near the bottom of the document, several -release-related terms are defined. - -This document also contains a link to the **Feature tracking sheet**, which is -the official way to find out about all new features scheduled to go into the -release. - -The release team document lists who is responsible for each release role. If -it's not clear who to talk to about a specific feature or question you have, -either attend the release meeting to ask your question, or contact the release -lead so that they can redirect you. - -The release notes draft is a good place to find out about -specific features, changes, deprecations, and more about the release. The -content is not finalized until late in the release cycle, so use caution. - -### Feature tracking sheet - -The feature tracking sheet [for a given Kubernetes release](https://github.com/kubernetes/sig-release/tree/master/releases) -lists each feature that is planned for a release. -Each line item includes the name of the feature, a link to the feature's main -GitHub issue, its stability level (Alpha, Beta, or Stable), the SIG and -individual responsible for implementing it, whether it -needs docs, a draft release note for the feature, and whether it has been -merged. Keep the following in mind: - -- Beta and Stable features are generally a higher documentation priority than - Alpha features. -- It's hard to test (and therefore to document) a feature that hasn't been merged, - or is at least considered feature-complete in its PR. -- Determining whether a feature needs documentation is a manual process. Even if - a feature is not marked as needing docs, you may need to document the feature. - -## For developers or other SIG members - -This section is information for members of other Kubernetes SIGs documenting new features -for a release. - -If you are a member of a SIG developing a new feature for Kubernetes, you need -to work with SIG Docs to be sure your feature is documented in time for the -release. Check the -[feature tracking spreadsheet](https://github.com/kubernetes/sig-release/tree/master/releases) -or check in the `#sig-release` Kubernetes Slack channel to verify scheduling details and -deadlines. - -### Open a placeholder PR - -1. Open a **draft** pull request against the -`dev-{{< skew nextMinorVersion >}}` branch in the `kubernetes/website` repository, with a small -commit that you will amend later. To create a draft pull request, use the -Create Pull Request drop-down and select **Create Draft Pull Request**, -then click **Draft Pull Request**. -2. Edit the pull request description to include links to [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) -PR(s) and [kubernetes/enhancements](https://github.com/kubernetes/enhancements) issue(s). -3. Leave a comment on the related [kubernetes/enhancements](https://github.com/kubernetes/enhancements) -issue with a link to the PR to notify the docs person managing this release that -the feature docs are coming and should be tracked for the release. - -If your feature does not need -any documentation changes, make sure the sig-release team knows this, by -mentioning it in the `#sig-release` Slack channel. If the feature does need -documentation but the PR is not created, the feature may be removed from the -milestone. - -### PR ready for review - -When ready, populate your placeholder PR with feature documentation and change -the state of the PR from draft to **ready for review**. To mark a pull request -as ready for review, navigate to the merge box and click **Ready for review**. - -Do your best to describe your feature and how to use it. If you need help structuring your documentation, ask in the `#sig-docs` Slack channel. - -When you complete your content, the documentation person assigned to your feature reviews it. -To ensure technical accuracy, the content may also require a technical review from corresponding SIG(s). -Use their suggestions to get the content to a release ready state. - -If your feature is an Alpha or Beta feature and is behind a feature gate, -make sure you add it to [Alpha/Beta Feature gates](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features) -table as part of your pull request. With new feature gates, a description of -the feature gate is also required. If your feature is GA'ed or deprecated, -make sure to move it from the -[Feature gates for Alpha/Feature](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features) table -to [Feature gates for graduated or deprecated features](/docs/reference/command-line-tools-reference/feature-gates-removed/#feature-gates-that-are-removed) -table with Alpha and Beta history intact. - -If your feature needs documentation and the first draft -content is not received, the feature may be removed from the milestone. - -### All PRs reviewed and ready to merge - -If your PR has not yet been merged into the `dev-{{< skew nextMinorVersion >}}` branch by the release deadline, work with the -docs person managing the release to get it in by the deadline. If your feature needs -documentation and the docs are not ready, the feature may be removed from the -milestone. \ No newline at end of file diff --git a/content/en/docs/Contribute/new-content/open-a-pr.md b/content/en/docs/Contribute/new-content/open-a-pr.md deleted file mode 100644 index 382befe11694..000000000000 --- a/content/en/docs/Contribute/new-content/open-a-pr.md +++ /dev/null @@ -1,628 +0,0 @@ ---- -title: Opening a pull request -content_type: concept -weight: 10 -card: - name: contribute - weight: 40 ---- - - - -{{< note >}} -**Code developers**: If you are documenting a new feature for an -upcoming Kubernetes release, see -[Document a new feature](/docs/contribute/new-content/new-features/). -{{< /note >}} - -To contribute new content pages or improve existing content pages, open a pull request (PR). -Make sure you follow all the requirements in the -[Before you begin](/docs/contribute/new-content/) section. - -If your change is small, or you're unfamiliar with git, read -[Changes using GitHub](#changes-using-github) to learn how to edit a page. - -If your changes are large, read [Work from a local fork](#fork-the-repo) to learn how to make -changes locally on your computer. - - - -## Changes using GitHub - -If you're less experienced with git workflows, here's an easier method of -opening a pull request. Figure 1 outlines the steps and the details follow. - - - - -{{< mermaid >}} -flowchart LR -A([fa:fa-user New
Contributor]) --- id1[(kubernetes/website
GitHub)] -subgraph tasks[Changes using GitHub] -direction TB - 0[ ] -.- - 1[1. Edit this page] --> 2[2. Use GitHub markdown
editor to make changes] - 2 --> 3[3. fill in Propose file change] - -end -subgraph tasks2[ ] -direction TB -4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] -6 --> 7[7. select Create pull request] -end - -id1 --> tasks --> tasks2 - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; -classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 -class A,1,2,3,4,5,6,7 grey -class 0 spacewhite -class tasks,tasks2 white -class id1 k8s -{{}} - -Figure 1. Steps for opening a PR using GitHub. - -1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. - -1. Make your changes in the GitHub markdown editor. - -1. Below the editor, fill in the **Propose file change** form. - In the first field, give your commit message a title. - In the second field, provide a description. - - {{< note >}} - Do not use any [GitHub Keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) - in your commit message. You can add those to the pull request description later. - {{< /note >}} - -1. Select **Propose file change**. - -1. Select **Create pull request**. - -1. The **Open a pull request** screen appears. Fill in the form: - - - The **Subject** field of the pull request defaults to the commit summary. - You can change it if needed. - - The **Body** contains your extended commit message, if you have one, - and some template text. Add the - details the template text asks for, then delete the extra template text. - - Leave the **Allow edits from maintainers** checkbox selected. - - {{< note >}} - PR descriptions are a great way to help reviewers understand your change. - For more information, see [Opening a PR](#open-a-pr). - {{}} - -1. Select **Create pull request**. - -### Addressing feedback in GitHub - -Before merging a pull request, Kubernetes community members review and -approve it. The `k8s-ci-robot` suggests reviewers based on the nearest -owner mentioned in the pages. If you have someone specific in mind, -leave a comment with their GitHub username in it. - -If a reviewer asks you to make changes: - -1. Go to the **Files changed** tab. -1. Select the pencil (edit) icon on any files changed by the pull request. -1. Make the changes requested. -1. Commit the changes. - -If you are waiting on a reviewer, reach out once every 7 days. You can also post a message in the -`#sig-docs` Slack channel. - -When your review is complete, a reviewer merges your PR and your changes go live a few minutes later. - -## Work from a local fork {#fork-the-repo} - -If you're more experienced with git, or if your changes are larger than a few lines, -work from a local fork. - -Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed -on your computer. You can also use a git UI application. - -Figure 2 shows the steps to follow when you work from a local fork. The details for each step follow. - - - - -{{< mermaid >}} -flowchart LR -1[Fork the kubernetes/website
repository] --> 2[Create local clone
and set upstream] -subgraph changes[Your changes] -direction TB -S[ ] -.- -3[Create a branch
example: my_new_branch] --> 3a[Make changes using
text editor] --> 4["Preview your changes
locally using Hugo
(localhost:1313)
or build container image"] -end -subgraph changes2[Commit / Push] -direction TB -T[ ] -.- -5[Commit your changes] --> 6[Push commit to
origin/my_new_branch] -end - -2 --> changes --> changes2 - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; -classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 -class 1,2,3,3a,4,5,6 grey -class S,T spacewhite -class changes,changes2 white -{{}} - -Figure 2. Working from a local fork to make your changes. - -### Fork the kubernetes/website repository - -1. Navigate to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository. -1. Select **Fork**. - -### Create a local clone and set the upstream - -1. In a terminal window, clone your fork and update the [Docsy Hugo theme](https://github.com/google/docsy#readme): - - ```shell - git clone git@github.com:/website - cd website - git submodule update --init --recursive --depth 1 - ``` - -1. Navigate to the new `website` directory. Set the `kubernetes/website` repository as the `upstream` remote: - - ```shell - cd website - - git remote add upstream https://github.com/kubernetes/website.git - ``` - -1. Confirm your `origin` and `upstream` repositories: - - ```shell - git remote -v - ``` - - Output is similar to: - - ```none - origin git@github.com:/website.git (fetch) - origin git@github.com:/website.git (push) - upstream https://github.com/kubernetes/website.git (fetch) - upstream https://github.com/kubernetes/website.git (push) - ``` - -1. Fetch commits from your fork's `origin/main` and `kubernetes/website`'s `upstream/main`: - - ```shell - git fetch origin - git fetch upstream - ``` - - This makes sure your local repository is up to date before you start making changes. - - {{< note >}} - This workflow is different than the - [Kubernetes Community GitHub Workflow](https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md). - You do not need to merge your local copy of `main` with `upstream/main` before pushing updates - to your fork. - {{< /note >}} - -### Create a branch - -1. Decide which branch base to your work on: - - - For improvements to existing content, use `upstream/main`. - - For new content about existing features, use `upstream/main`. - - For localized content, use the localization's conventions. For more information, see - [localizing Kubernetes documentation](/docs/contribute/localization/). - - For new features in an upcoming Kubernetes release, use the feature branch. For more - information, see [documenting for a release](/docs/contribute/new-content/new-features/). - - For long-running efforts that multiple SIG Docs contributors collaborate on, - like content reorganization, use a specific feature branch created for that effort. - - If you need help choosing a branch, ask in the `#sig-docs` Slack channel. - -1. Create a new branch based on the branch identified in step 1. This example assumes the base - branch is `upstream/main`: - - ```shell - git checkout -b upstream/main - ``` - -1. Make your changes using a text editor. - -At any time, use the `git status` command to see what files you've changed. - -### Commit your changes - -When you are ready to submit a pull request, commit your changes. - -1. In your local repository, check which files you need to commit: - - ```shell - git status - ``` - - Output is similar to: - - ```none - On branch - Your branch is up to date with 'origin/'. - - Changes not staged for commit: - (use "git add ..." to update what will be committed) - (use "git checkout -- ..." to discard changes in working directory) - - modified: content/en/docs/contribute/new-content/contributing-content.md - - no changes added to commit (use "git add" and/or "git commit -a") - ``` - -1. Add the files listed under **Changes not staged for commit** to the commit: - - ```shell - git add - ``` - - Repeat this for each file. - -1. After adding all the files, create a commit: - - ```shell - git commit -m "Your commit message" - ``` - - {{< note >}} - Do not use any [GitHub Keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) - in your commit message. You can add those to the pull request - description later. - {{< /note >}} - -1. Push your local branch and its new commit to your remote fork: - - ```shell - git push origin - ``` - -### Preview your changes locally {#preview-locally} - -It's a good idea to preview your changes locally before pushing them or opening a pull request. -A preview lets you catch build errors or markdown formatting problems. - -You can either build the website's container image or run Hugo locally. Building the container -image is slower but displays [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/), which can -be useful for debugging. - -{{< tabs name="tab_with_hugo" >}} -{{% tab name="Hugo in a container" %}} - -{{< note >}} -The commands below use Docker as default container engine. Set the `CONTAINER_ENGINE` environment -variable to override this behaviour. -{{< /note >}} - -1. Build the container image locally - _You only need this step if you are testing a change to the Hugo tool itself_ - - ```shell - # Run this in a terminal (if required) - make container-image - ``` - -1. Start Hugo in a container: - - ```shell - # Run this in a terminal - make container-serve - ``` - -1. In a web browser, navigate to `https://localhost:1313`. Hugo watches the - changes and rebuilds the site as needed. - -1. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, - or close the terminal window. - -{{% /tab %}} -{{% tab name="Hugo on the command line" %}} - -Alternately, install and use the `hugo` command on your computer: - -1. Install the [Hugo](https://gohugo.io/getting-started/installing/) version specified in - [`website/netlify.toml`](https://raw.githubusercontent.com/kubernetes/website/main/netlify.toml). - -1. If you have not updated your website repository, the `website/themes/docsy` directory is empty. - The site cannot build without a local copy of the theme. To update the website theme, run: - - ```shell - git submodule update --init --recursive --depth 1 - ``` - -1. In a terminal, go to your Kubernetes website repository and start the Hugo server: - - ```shell - cd /website - hugo server --buildFuture - ``` - -1. In a web browser, navigate to `https://localhost:1313`. Hugo watches the - changes and rebuilds the site as needed. - -1. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, - or close the terminal window. - -{{% /tab %}} -{{< /tabs >}} - -### Open a pull request from your fork to kubernetes/website {#open-a-pr} - -Figure 3 shows the steps to open a PR from your fork to the [kubernetes/website](https://github.com/kubernetes/website). The details follow. - -Please, note that contributors can mention `kubernetes/website` as `k/website`. - - - - -{{< mermaid >}} -flowchart LR -subgraph first[ ] -direction TB -1[1. Go to kubernetes/website repository] --> 2[2. Select New Pull Request] -2 --> 3[3. Select compare across forks] -3 --> 4[4. Select your fork from
head repository drop-down menu] -end -subgraph second [ ] -direction TB -5[5. Select your branch from
the compare drop-down menu] --> 6[6. Select Create Pull Request] -6 --> 7[7. Add a description
to your PR] -7 --> 8[8. Select Create pull request] -end - -first --> second - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -class 1,2,3,4,5,6,7,8 grey -class first,second white -{{}} - -Figure 3. Steps to open a PR from your fork to the [kubernetes/website](https://github.com/kubernetes/website). - -1. In a web browser, go to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository. -1. Select **New Pull Request**. -1. Select **compare across forks**. -1. From the **head repository** drop-down menu, select your fork. -1. From the **compare** drop-down menu, select your branch. -1. Select **Create Pull Request**. -1. Add a description for your pull request: - - - **Title** (50 characters or less): Summarize the intent of the change. - - **Description**: Describe the change in more detail. - - - If there is a related GitHub issue, include `Fixes #12345` or `Closes #12345` in the - description. GitHub's automation closes the mentioned issue after merging the PR if used. - If there are other related PRs, link those as well. - - If you want advice on something specific, include any questions you'd like reviewers to - think about in your description. - -1. Select the **Create pull request** button. - -Congratulations! Your pull request is available in [Pull requests](https://github.com/kubernetes/website/pulls). - -After opening a PR, GitHub runs automated tests and tries to deploy a preview using -[Netlify](https://www.netlify.com/). - -- If the Netlify build fails, select **Details** for more information. -- If the Netlify build succeeds, select **Details** opens a staged version of the Kubernetes - website with your changes applied. This is how reviewers check your changes. - -GitHub also automatically assigns labels to a PR, to help reviewers. You can add them too, if -needed. For more information, see [Adding and removing issue labels](/docs/contribute/review/for-approvers/#adding-and-removing-issue-labels). - -### Addressing feedback locally - -1. After making your changes, amend your previous commit: - - ```shell - git commit -a --amend - ``` - - - `-a`: commits all changes - - `--amend`: amends the previous commit, rather than creating a new one - -1. Update your commit message if needed. - -1. Use `git push origin ` to push your changes and re-run the Netlify tests. - - {{< note >}} - If you use `git commit -m` instead of amending, you must [squash your commits](#squashing-commits) - before merging. - {{< /note >}} - -#### Changes from reviewers - -Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits. - -1. Fetch commits from your remote fork and rebase your working branch: - - ```shell - git fetch origin - git rebase origin/ - ``` - -1. After rebasing, force-push new changes to your fork: - - ```shell - git push --force-with-lease origin - ``` - -#### Merge conflicts and rebasing - -{{< note >}} -For more information, see [Git Branching - Basic Branching and Merging](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts), -[Advanced Merging](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging), or ask in the -`#sig-docs` Slack channel for help. -{{< /note >}} - -If another contributor commits changes to the same file in another PR, it can create a merge -conflict. You must resolve all merge conflicts in your PR. - -1. Update your fork and rebase your local branch: - - ```shell - git fetch origin - git rebase origin/ - ``` - - Then force-push the changes to your fork: - - ```shell - git push --force-with-lease origin - ``` - -1. Fetch changes from `kubernetes/website`'s `upstream/main` and rebase your branch: - - ```shell - git fetch upstream - git rebase upstream/main - ``` - -1. Inspect the results of the rebase: - - ```shell - git status - ``` - - This results in a number of files marked as conflicted. - -1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. - Resolve the conflict and delete the conflict marker. - - {{< note >}} - For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). - {{< /note >}} - -1. Add the files to the changeset: - - ```shell - git add - ``` - -1. Continue the rebase: - - ```shell - git rebase --continue - ``` - -1. Repeat steps 2 to 5 as needed. - - After applying all commits, the `git status` command shows that the rebase is complete. - -1. Force-push the branch to your fork: - - ```shell - git push --force-with-lease origin - ``` - - The pull request no longer shows any conflicts. - -### Squashing commits - -{{< note >}} -For more information, see [Git Tools - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History), -or ask in the `#sig-docs` Slack channel for help. -{{< /note >}} - -If your PR has multiple commits, you must squash them into a single commit before merging your PR. -You can check the number of commits on your PR's **Commits** tab or by running the `git log` -command locally. - -{{< note >}} -This topic assumes `vim` as the command line text editor. -{{< /note >}} - -1. Start an interactive rebase: - - ```shell - git rebase -i HEAD~ - ``` - - Squashing commits is a form of rebasing. The `-i` switch tells git you want to rebase interactively. - `HEAD~}} - For more information, see [Interactive Mode](https://git-scm.com/docs/git-rebase#_interactive_mode). - {{< /note >}} - -1. Start editing the file. - - Change the original text: - - ```none - pick d875112ca Original commit - pick 4fa167b80 Address feedback 1 - pick 7d54e15ee Address feedback 2 - ``` - - To: - - ```none - pick d875112ca Original commit - squash 4fa167b80 Address feedback 1 - squash 7d54e15ee Address feedback 2 - ``` - - This squashes commits `4fa167b80 Address feedback 1` and `7d54e15ee Address feedback 2` into - `d875112ca Original commit`, leaving only `d875112ca Original commit` as a part of the timeline. - -1. Save and exit your file. - -1. Push your squashed commit: - - ```shell - git push --force-with-lease origin - ``` - -## Contribute to other repos - -The [Kubernetes project](https://github.com/kubernetes) contains 50+ repositories. Many of these -repositories contain documentation: user-facing help text, error messages, API references or code -comments. - -If you see text you'd like to improve, use GitHub to search all repositories in the Kubernetes -organization. This can help you figure out where to submit your issue or PR. - -Each repository has its own processes and procedures. Before you file an issue or submit a PR, -read that repository's `README.md`, `CONTRIBUTING.md`, and `code-of-conduct.md`, if they exist. - -Most repositories use issue and PR templates. Have a look through some open issues and PRs to get -a feel for that team's processes. Make sure to fill out the templates with as much detail as -possible when you file issues or PRs. - -## {{% heading "whatsnext" %}} - -- Read [Reviewing](/docs/contribute/review/reviewing-prs) to learn more about the review process. - diff --git a/content/en/docs/Contribute/roles-and-responsibilities.md b/content/en/docs/Contribute/roles-and-responsibilities.md deleted file mode 100644 index 19c9190fd88d..000000000000 --- a/content/en/docs/Contribute/roles-and-responsibilities.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Roles and responsibilities -content_type: concept -weight: 10 ---- - - - -Anyone can contribute to Kubernetes. As your contributions to SIG Docs grow, -you can apply for different levels of membership in the community. -These roles allow you to take on more responsibility within the community. -Each role requires more time and commitment. The roles are: - -- Anyone: regular contributors to the Kubernetes documentation -- Members: can assign and triage issues and provide non-binding review on pull requests -- Reviewers: can lead reviews on documentation pull requests and can vouch for a change's quality -- Approvers: can lead reviews on documentation and merge changes - - - -## Anyone - -Anyone with a GitHub account can contribute to Kubernetes. SIG Docs welcomes all new contributors! - -Anyone can: - -- Open an issue in any [Kubernetes](https://github.com/kubernetes/) - repository, including - [`kubernetes/website`](https://github.com/kubernetes/website) -- Give non-binding feedback on a pull request -- Contribute to a localization -- Suggest improvements on [Slack](https://slack.k8s.io/) or the - [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). - -After [signing the CLA](https://github.com/kubernetes/community/blob/master/CLA.md), anyone can also: - -- Open a pull request to improve existing content, add new content, or write a blog post or case study -- Create diagrams, graphics assets, and embeddable screencasts and videos - -For more information, see [contributing new content](/docs/contribute/new-content/). - -## Members - -A member is someone who has submitted multiple pull requests to -`kubernetes/website`. Members are a part of the -[Kubernetes GitHub organization](https://github.com/kubernetes). - -Members can: - -- Do everything listed under [Anyone](#anyone) -- Use the `/lgtm` comment to add the LGTM (looks good to me) label to a pull request - - {{< note >}} - Using `/lgtm` triggers automation. If you want to provide non-binding - approval, commenting "LGTM" works too! - {{< /note >}} - -- Use the `/hold` comment to block merging for a pull request -- Use the `/assign` comment to assign a reviewer to a pull request -- Provide non-binding review on pull requests -- Use automation to triage and categorize issues -- Document new features - -### Becoming a member - -After submitting at least 5 substantial pull requests and meeting the other -[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#member): - -1. Find two [reviewers](#reviewers) or [approvers](#approvers) to - [sponsor](/docs/contribute/advanced#sponsor-a-new-contributor) your - membership. - - Ask for sponsorship in the [#sig-docs channel on Slack](https://kubernetes.slack.com) or on the - [SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). - - {{< note >}} - Don't send a direct email or Slack direct message to an individual - SIG Docs member. You must request sponsorship before submitting your application. - {{< /note >}} - -1. Open a GitHub issue in the - [`kubernetes/org`](https://github.com/kubernetes/org/) repository. Use the - **Organization Membership Request** issue template. - -1. Let your sponsors know about the GitHub issue. You can either: - - Mention their GitHub username in an issue (`@`) - - Send them the issue link using Slack or email. - - Sponsors will approve your request with a `+1` vote. Once your sponsors - approve the request, a Kubernetes GitHub admin adds you as a member. - Congratulations! - - If your membership request is not accepted you will receive feedback. - After addressing the feedback, apply again. - -1. Accept the invitation to the Kubernetes GitHub organization in your email account. - - {{< note >}} - GitHub sends the invitation to the default email address in your account. - {{< /note >}} - -## Reviewers - -Reviewers are responsible for reviewing open pull requests. Unlike member -feedback, the PR author must address reviewer feedback. Reviewers are members of the -[@kubernetes/sig-docs-{language}-reviews](https://github.com/orgs/kubernetes/teams?query=sig-docs) -GitHub team. - -Reviewers can: - -- Do everything listed under [Anyone](#anyone) and [Members](#members) -- Review pull requests and provide binding feedback - - {{< note >}} - To provide non-binding feedback, prefix your comments with a phrase like "Optionally: ". - {{< /note >}} - -- Edit user-facing strings in code -- Improve code comments - -You can be a SIG Docs reviewer, or a reviewer for docs in a specific subject area. - -### Assigning reviewers to pull requests - -Automation assigns reviewers to all pull requests. You can request a -review from a specific person by commenting: `/assign -[@_github_handle]`. - -If the assigned reviewer has not commented on the PR, another reviewer can -step in. You can also assign technical reviewers as needed. - -### Using `/lgtm` - -LGTM stands for "Looks good to me" and indicates that a pull request is -technically accurate and ready to merge. All PRs need a `/lgtm` comment from a -reviewer and a `/approve` comment from an approver to merge. - -A `/lgtm` comment from reviewer is binding and triggers automation that adds the `lgtm` label. - -### Becoming a reviewer - -When you meet the -[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer), -you can become a SIG Docs reviewer. Reviewers in other SIGs must apply -separately for reviewer status in SIG Docs. - -To apply: - -1. Open a pull request that adds your GitHub username to a section of the - [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) file - in the `kubernetes/website` repository. - - {{< note >}} - If you aren't sure where to add yourself, add yourself to `sig-docs-en-reviews`. - {{< /note >}} - -1. Assign the PR to one or more SIG-Docs approvers (usernames listed under - `sig-docs-{language}-owners`). - -If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, -[K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) -assigns and suggests you as a reviewer on new pull requests. - -## Approvers - -Approvers review and approve pull requests for merging. Approvers are members of the -[@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs) -GitHub teams. - -Approvers can do the following: - -- Everything listed under [Anyone](#anyone), [Members](#members) and [Reviewers](#reviewers) -- Publish contributor content by approving and merging pull requests using the `/approve` comment -- Propose improvements to the style guide -- Propose improvements to docs tests -- Propose improvements to the Kubernetes website or other tooling - -If the PR already has a `/lgtm`, or if the approver also comments with -`/lgtm`, the PR merges automatically. A SIG Docs approver should only leave a -`/lgtm` on a change that doesn't need additional technical review. - - -### Approving pull requests - -Approvers and SIG Docs leads are the only ones who can merge pull requests -into the website repository. This comes with certain responsibilities. - -- Approvers can use the `/approve` command, which merges PRs into the repo. - - {{< warning >}} - A careless merge can break the site, so be sure that when you merge something, you mean it. - {{< /warning >}} - -- Make sure that proposed changes meet the - [documentation content guide](/docs/contribute/style/content-guide/). - - If you ever have a question, or you're not sure about something, feel free - to call for additional review. - -- Verify that Netlify tests pass before you `/approve` a PR. - - Netlify tests must pass before approving - -- Visit the Netlify page preview for a PR to make sure things look good before approving. - -- Participate in the - [PR Wrangler rotation schedule](https://github.com/kubernetes/website/wiki/PR-Wranglers) - for weekly rotations. SIG Docs expects all approvers to participate in this - rotation. See [PR wranglers](/docs/contribute/participate/pr-wranglers/). - for more details. - -### Becoming an approver - -When you meet the -[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#approver), -you can become a SIG Docs approver. Approvers in other SIGs must apply -separately for approver status in SIG Docs. - -To apply: - -1. Open a pull request adding yourself to a section of the - [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) - file in the `kubernetes/website` repository. - - {{< note >}} - If you aren't sure where to add yourself, add yourself to `sig-docs-en-owners`. - {{< /note >}} - -2. Assign the PR to one or more current SIG Docs approvers. - -If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, -[@k8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) -assigns and suggests you as a reviewer on new pull requests. - -## {{% heading "whatsnext" %}} - -- Read about [PR wrangling](/docs/contribute/participate/pr-wranglers/), a role all approvers take on rotation. diff --git a/content/en/docs/Contribute/suggesting-improvements.md b/content/en/docs/Contribute/suggesting-improvements.md deleted file mode 100644 index aac6ce1c1351..000000000000 --- a/content/en/docs/Contribute/suggesting-improvements.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Suggesting content improvements -content_type: concept -weight: 10 -card: - name: contribute - weight: 15 - anchors: - - anchor: "#opening-an-issue" - title: Suggest content improvements ---- - - - -If you notice an issue with Kubernetes documentation or have an idea for new content, then open an issue. All you need is a [GitHub account](https://github.com/join) and a web browser. - -In most cases, new work on Kubernetes documentation begins with an issue in GitHub. Kubernetes contributors -then review, categorize and tag issues as needed. Next, you or another member -of the Kubernetes community open a pull request with changes to resolve the issue. - - - - - -## Opening an issue - -If you want to suggest improvements to existing content or notice an error, then open an issue. - -1. Click the **Create an issue** link on the right sidebar. This redirects you - to a GitHub issue page pre-populated with some headers. -2. Describe the issue or suggestion for improvement. Provide as many details as you can. -3. Click **Submit new issue**. - -After submitting, check in on your issue occasionally or turn on GitHub notifications. -Reviewers and other community members might ask questions before -they can take action on your issue. - -## Suggesting new content - -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 an issue**. -- Go to [GitHub](https://github.com/kubernetes/website/issues/new/) and file the issue directly. - -## How to file great issues - - -Keep the following in mind when filing an issue: - -- Provide a clear issue description. Describe what specifically is missing, out of date, - wrong, or needs improvement. -- Explain the specific impact the issue has on users. -- Limit the scope of a given issue to a reasonable unit of work. For problems - with a large scope, break them down into smaller issues. For example, "Fix the security docs" - is too broad, but "Add details to the 'Restricting network access' topic" is specific enough - to be actionable. -- Search the existing issues to see if there's anything related or similar to the - new issue. -- If the new issue relates to another issue or pull request, refer to it - either by its full URL or by the issue or pull request number prefixed - with a `#` character. For example, `Introduced by #987654`. -- Follow the [Code of Conduct](/community/code-of-conduct/). Respect your -fellow contributors. For example, "The docs are terrible" is not - helpful or polite feedback. - - From 9812ebea1275928f11fc77eeea725269363a729c Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 13:06:32 +0100 Subject: [PATCH 04/62] Blog post guide --- content/en/docs/Contribute/_index.md | 2 +- .../en/docs/Contribute/blogs-case-studies.md | 181 +++--------------- 2 files changed, 32 insertions(+), 151 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index b80faf030304..2924b4410bd4 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -510,5 +510,5 @@ fellow contributors. For example, "The docs are terrible" is not - Visit the [OpenTelemetry community site](/community/). - Add your application to the [Registry](/ecosystem). -- Submit a [blog post or case study](/docs/contribute/new-content/blogs-case-studies/). +- Submit a [blog post or case study](/docs/contribute/blogs-case-studies/). diff --git a/content/en/docs/Contribute/blogs-case-studies.md b/content/en/docs/Contribute/blogs-case-studies.md index 72d234e7a84b..7c855689b959 100644 --- a/content/en/docs/Contribute/blogs-case-studies.md +++ b/content/en/docs/Contribute/blogs-case-studies.md @@ -1,58 +1,45 @@ --- -title: Submitting blog posts and case studies -linktitle: Blogs and case studies +title: Submit a blog post +linktitle: Submit a blog post slug: blogs-case-studies -content_type: concept weight: 30 +cSpell:ignore: --- +The [OpenTelemetry blog](/blog/) communicates new features, community reports, +and any news that might be relevant to the OpenTelemetry community. This +includes end users and developers. Anyone can write a blog post and submit it +for review. - +## Submit a post -Anyone can write a blog post and submit it for review. -Case studies require extensive review before they're approved. +Blog posts should not be commercial in nature and should consist of original +content that applies broadly to the OpenTelemetry community. Appropriate blog +content includes: - - -## The Kubernetes Blog - -The Kubernetes blog is used by the project to communicate new features, community reports, and any -news that might be relevant to the Kubernetes community. This includes end users and developers. -Most of the blog's content is about things happening in the core project, but we encourage you to -submit about things happening elsewhere in the ecosystem too! - -Anyone can write a blog post and submit it for review. - -### Submit a Post - -Blog posts should not be commercial in nature and should consist of original content that applies -broadly to the Kubernetes community. Appropriate blog content includes: - -- New Kubernetes capabilities -- Kubernetes projects updates +- New OpenTelemetry capabilities +- OpenTelemetry projects updates - Updates from Special Interest Groups - Tutorials and walkthroughs -- Thought leadership around Kubernetes -- Kubernetes Partner OSS integration -- **Original content only** +- Thought leadership around OpenTelemetry +- OpenTelemetry Partner OSS integration Unsuitable content includes: - Vendor product pitches - Partner updates without an integration and customer story -- Syndicated posts (language translations ok) To submit a blog post, follow these steps: -1. [Sign the CLA](https://github.com/kubernetes/community/blob/master/CLA.md) +1. [Sign the CLA](https://docs.linuxfoundation.org/lfx/easycla/contributors) if you have not yet done so. 1. Have a look at the Markdown format for existing blog posts in the - [website repository](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts). + [opentelemetry.io repository](https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/blog). 1. Write out your blog post in a text editor of your choice. -1. On the same link from step 2, click the Create new file button. Paste your content into the editor. +1. On the same link from step 2, select **Create new file**. Paste your content into the editor. Name the file to match the proposed title of the blog post, but don’t put the date in the file name. The blog reviewers will work with you on the final file name and the date the blog will be published. @@ -61,139 +48,33 @@ To submit a blog post, follow these steps: 1. A blog post reviewer will review your submission and work with you on feedback and final details. When the blog post is approved, the blog will be scheduled for publication. -### Guidelines and expectations +## Guidelines and expectations - Blog posts should not be vendor pitches. - - Articles must contain content that applies broadly to the Kubernetes community. For example, a - submission should focus on upstream Kubernetes as opposed to vendor-specific configurations. + - Articles must contain content that applies broadly to the OpenTelemetry community. For example, a + submission should focus on upstream OpenTelemetry as opposed to vendor-specific configurations. Check the [Documentation style guide](/docs/contribute/style/content-guide/#what-s-allowed) for - what is typically allowed on Kubernetes properties. - - Links should primarily be to the official Kubernetes documentation. When using external + what is typically allowed on OpenTelemetry properties. + - Links should primarily be to the official OpenTelemetry documentation. When using external references, links should be diverse - For example a submission shouldn't contain only links back to a single company's blog. - - Sometimes this is a delicate balance. The [blog team](https://kubernetes.slack.com/messages/sig-docs-blog/) - is there to give guidance on whether a post is appropriate for the Kubernetes blog, so don't - hesitate to reach out. - Blog posts are not published on specific dates. - - Articles are reviewed by community volunteers. We'll try our best to accommodate specific + - Articles are reviewed by community volunteers. We'll try our best to accommodate specific timing, but we make no guarantees. - - Many core parts of the Kubernetes projects submit blog posts during release windows, delaying + - Many core parts of the OpenTelemetry projects submit blog posts during release windows, delaying publication times. Consider submitting during a quieter period of the release cycle. - If you are looking for greater coordination on post release dates, coordinating with [CNCF marketing](https://www.cncf.io/about/contact/) is a more appropriate choice than submitting a blog post. - - Sometimes reviews can get backed up. If you feel your review isn't getting the attention it needs, - you can reach out to the blog team on the [`#sig-docs-blog` Slack channel](https://kubernetes.slack.com/messages/sig-docs-blog/) - to ask in real time. -- Blog posts should be relevant to Kubernetes users. +- Blog posts should be relevant to OpenTelemetry users. - - Topics related to participation in or results of Kubernetes SIGs activities are always on - topic (see the work in the [Contributor Comms Team](https://github.com/kubernetes/community/blob/master/communication/contributor-comms/blogging-resources/blog-guidelines.md#contributor-comms-blog-guidelines) - for support on these posts). - - The components of Kubernetes are purposely modular, so tools that use existing integration - points like CNI and CSI are on topic. + - Topics related to participation in or results of OpenTelemetry SIGs activities are always on + topic. - Posts about other CNCF projects may or may not be on topic. We recommend asking the blog team before submitting a draft. - - Many CNCF projects have their own blog. These are often a better choice for posts. There are - times of major feature or milestone for a CNCF project that users would be interested in - reading on the Kubernetes blog. - - Blog posts about contributing to the Kubernetes project should be in the - [Kubernetes Contributors site](https://kubernetes.dev) - -- Blog posts should be original content - - - The official blog is not for repurposing existing content from a third party as new content. - - The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows - commercial use of the content for commercial purposes, but not the other way around. - -- Blog posts should aim to be future proof - - - Given the development velocity of the project, we want evergreen content that won't require - updates to stay accurate for the reader. - - It can be a better choice to add a tutorial or update official documentation than to write a - high level overview as a blog post. - - Consider concentrating the long technical content as a call to action of the blog post, and - focus on the problem space or why readers should care. - -### Technical Considerations for submitting a blog post - -Submissions need to be in Markdown format to be used by the [Hugo](https://gohugo.io/) generator -for the blog. There are [many resources available](https://gohugo.io/documentation/) on how to use -this technology stack. - -We recognize that this requirement makes the process more difficult for less-familiar folks to -submit, and we're constantly looking at solutions to lower this bar. If you have ideas on how to -lower the barrier, please volunteer to help out. - -The SIG Docs [blog subproject](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject) -manages the review process for blog posts. For more information, see -[Submit a post](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject#submit-a-post). - -To submit a blog post follow these directions: - -- [Open a pull request](/docs/contribute/new-content/open-a-pr/#fork-the-repo) with a new blog post. - New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/main/content/en/blog/_posts) - directory. - -- Ensure that your blog post follows the correct naming conventions and the following frontmatter - (metadata) information: - - - The Markdown file name must follow the format `YYYY-MM-DD-Your-Title-Here.md`. For example, - `2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md`. - - Do **not** include dots in the filename. A name like `2020-01-01-whats-new-in-1.19.md` causes - failures during a build. - - The front matter must include the following: - - ```yaml - --- - layout: blog - title: "Your Title Here" - date: YYYY-MM-DD - slug: text-for-URL-link-here-no-spaces - --- - ``` - - - The first or initial commit message should be a short summary of the work being done and - should stand alone as a description of the blog post. Please note that subsequent edits to - your blog will be squashed into this main commit, so it should be as useful as possible. - - - Examples of a good commit message: - - _Add blog post on the foo kubernetes feature_ - - _blog: foobar announcement_ - - Examples of bad commit message: - - _Add blog post_ - - _._ - - _initial commit_ - - _draft post_ - - - The blog team will then review your PR and give you comments on things you might need to fix. - After that the bot will merge your PR and your blog post will be published. - - - If the content of the blog post contains only content that is not expected to require updates - to stay accurate for the reader, it can be marked as evergreen and exempted from the automatic - warning about outdated content added to blog posts older than one year. - - - To mark a blog post as evergreen, add this to the front matter: - - ```yaml - evergreen: true - ``` - - Examples of content that should not be marked evergreen: - - **Tutorials** that only apply to specific releases or versions and not all future versions - - References to pre-GA APIs or features - -## Submit a case study - -Case studies highlight how organizations are using Kubernetes to solve real-world problems. The -Kubernetes marketing team and members of the {{< glossary_tooltip text="CNCF" term_id="cncf" >}} -collaborate with you on all case studies. - -Have a look at the source for the -[existing case studies](https://github.com/kubernetes/website/tree/main/content/en/case-studies). - -Refer to the [case study guidelines](https://github.com/cncf/foundation/blob/master/case-study-guidelines.md) -and submit your request as outlined in the guidelines. - + - Many CNCF projects have their own blog. These are often a better choice for posts. There are + times of major feature or milestone for a CNCF project that users would be interested in + reading on the OpenTelemetry blog. From 22cb3eeb6df1d36e331002a17d1ffbed23afeb7e Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 13:18:43 +0100 Subject: [PATCH 05/62] 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 `
Configuration parameters
` 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/). - From cecf2abc351ff9e926e68f286240f0783cb478a4 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Mon, 11 Dec 2023 16:25:13 +0100 Subject: [PATCH 06/62] Edits --- content/en/docs/Contribute/style-guide.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index 01a4e22a7e86..c6b0adf7bbb6 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -6,7 +6,6 @@ cSpell:ignore: slug: style-guide --- - 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. From fee4daf99bdddc98078ea476a3cec661a2c786f2 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Mon, 11 Dec 2023 17:11:56 +0100 Subject: [PATCH 07/62] Fix errors --- content/en/docs/Contribute/_index.md | 160 +++-- .../en/docs/Contribute/blogs-case-studies.md | 62 +- content/en/docs/Contribute/style-guide.md | 677 +----------------- 3 files changed, 136 insertions(+), 763 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index c03fc9aa3ddc..8ccc13bbf113 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -2,7 +2,7 @@ title: Contribute description: Learn how to contribute to the OpenTelemetry documentation. weight: 200 -cSpell:ignore: +cSpell:ignore: --- You can open an issue about OpenTelemetry documentation, or contribute a change @@ -25,10 +25,10 @@ Conduct. To contribute, you need to be familiar with the following techs and tools: -* [git](https://git-scm.com/) -* [GitHub](https://lab.github.com/) -* Markdown (CommonMark) -* YAML +- [git](https://git-scm.com/) +- [GitHub](https://lab.github.com/) +- Markdown (CommonMark) +- YAML For technical details concerning how the documentation is built and tested locally, see the @@ -44,14 +44,14 @@ and . Pull requests from contributors who haven't signed the CLA fail the automated -tests. The name and email you provide must match those found in -your `git config`, and your git name and email must match those used for the -CNCF CLA. +tests. The name and email you provide must match those found in your +`git config`, and your git name and email must match those used for the CNCF +CLA. ## Contribute new content -{{< mermaid >}} -flowchart LR +```mermaid +flowchart LR subgraph first[How to contribute] direction TB T[ ] -.- @@ -66,9 +66,9 @@ classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,B,C,D,E,F,G,H grey class S,T spacewhite class first,second white -{{}} +``` -***Figure - Contributing new content*** +**_Figure - Contributing new content_** The previous figure presents the basic steps for new docs contributions. @@ -76,16 +76,16 @@ To contribute new content pages or improve existing content pages, open a pull request (PR): - If your change is small, or you're unfamiliar with Git, read -[Changes using GitHub](#changes-using-github) to learn how to edit a page. -- If your changes are large, read [Work from a local fork](#fork-the-repo) to learn how to make -changes locally on your computer. + [Changes using GitHub](#changes-using-github) to learn how to edit a page. +- If your changes are large, read [Work from a local fork](#fork-the-repo) to + learn how to make changes locally on your computer. ### Changes using GitHub {#changes-using-github} If you're less experienced with Git workflows, here's an easier method of opening a pull request. Figure 1 outlines the steps and the details follow. -{{< mermaid >}} +```mermaid flowchart LR A([fa:fa-user New
Contributor]) --- id1[(open-telemetry/opentelemetry.io
GitHub)] subgraph tasks[Changes using GitHub] @@ -98,7 +98,7 @@ end subgraph tasks2[ ] direction TB 4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] -6 --> 7[7. select Create pull request] +6 --> 7[7. select Create pull request] end id1 --> tasks --> tasks2 @@ -111,11 +111,12 @@ class A,1,2,3,4,5,6,7 grey class 0 spacewhite class tasks,tasks2 white class id1 k8s -{{}} +``` Figure 1. Steps for opening a PR using GitHub. -1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. +1. On the page where you see the issue, select the **Edit this page** option in + the right-hand side navigation panel. 1. Make your changes in the GitHub editor. @@ -125,7 +126,8 @@ Figure 1. Steps for opening a PR using GitHub. 1. Select **Create pull request**. -1. The **Open a pull request** screen appears. Your description helps reviewers understand your change. +1. The **Open a pull request** screen appears. Your description helps reviewers + understand your change. 1. Select **Create pull request**. @@ -155,7 +157,7 @@ on your computer. You can also use a user interface for Git. Figure 2 shows the steps to follow when you work from a local fork. The details for each step follow. -{{< mermaid >}} +```mermaid flowchart LR 1[Fork the open-telemetry/opentelemetry
repository] --> 2[Create local clone
and set upstream] subgraph changes[Your changes] @@ -178,13 +180,15 @@ classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class 1,2,3,3a,4,5,6 grey class S,T spacewhite class changes,changes2 white -{{}} +``` Figure 2. Working from a local fork to make your changes. #### Fork the open-telemetry/opentelemetry.io repository -1. Navigate to the [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) repository. +1. Navigate to the + [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) + repository. 1. Select **Fork**. #### Create a local clone and set the upstream @@ -197,7 +201,8 @@ Figure 2. Working from a local fork to make your changes. npm install ``` -1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream` remote: +1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream` + remote: ```shell git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git @@ -218,14 +223,16 @@ Figure 2. Working from a local fork to make your changes. upstream https://github.com/open-telemetry/opentelemetry.io.git (push) ``` -1. Fetch commits from your fork's `origin/main` and `open-telemetry/opentelemetry.io`'s `upstream/main`: +1. Fetch commits from your fork's `origin/main` and + `open-telemetry/opentelemetry.io`'s `upstream/main`: ```shell git fetch origin git fetch upstream ``` - This makes sure your local repository is up to date before you start making changes. + This makes sure your local repository is up to date before you start making + changes. #### Create a branch @@ -286,8 +293,8 @@ When you are ready to submit a pull request, commit your changes. #### Preview your changes locally {#preview-locally} -Preview your changes locally before pushing them or opening a pull request. -A preview lets you catch build errors or markdown formatting problems. +Preview your changes locally before pushing them or opening a pull request. A +preview lets you catch build errors or markdown formatting problems. To build and serve the site locally with Hugo, run the following command: @@ -307,7 +314,7 @@ Figure 3 shows the steps to open a PR from your fork to the [open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) . -{{< mermaid >}} +```mermaid flowchart LR subgraph first[ ] direction TB @@ -328,12 +335,14 @@ classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-si classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold class 1,2,3,4,5,6,7,8 grey class first,second white -{{}} +``` Figure 3. Steps to open a PR from your fork to the [open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). -1. In a web browser, go to the [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) repository. +1. In a web browser, go to the + [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) + repository. 1. Select **New Pull Request**. 1. Select **compare across forks**. 1. From the **head repository** drop-down menu, select your fork. @@ -341,32 +350,35 @@ Figure 3. Steps to open a PR from your fork to the 1. Select **Create Pull Request**. 1. Add a description for your pull request: - - **Title** (50 characters or less): Summarize the intent of the change. - - **Description**: Describe the change in more detail. + - **Title** (50 characters or less): Summarize the intent of the change. + - **Description**: Describe the change in more detail. - - If there is a related GitHub issue, include `Fixes #12345` or `Closes #12345` in the - description. GitHub's automation closes the mentioned issue after merging the PR if used. - If there are other related PRs, link those as well. - - If you want advice on something specific, include any questions you'd like reviewers to - think about in your description. + - If there is a related GitHub issue, include `Fixes #12345` or + `Closes #12345` in the description. GitHub's automation closes the + mentioned issue after merging the PR if used. If there are other related + PRs, link those as well. + - If you want advice on something specific, include any questions you'd + like reviewers to think about in your description. 1. Select the **Create pull request** button. Your pull request is available in [Pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls). -After opening a PR, GitHub runs automated tests and tries to deploy a preview using -[Netlify](https://www.netlify.com/). +After opening a PR, GitHub runs automated tests and tries to deploy a preview +using [Netlify](https://www.netlify.com/). - If the Netlify build fails, select **Details** for more information. -- If the Netlify build succeeds, select **Details** opens a staged version of the OpenTelemetry - website with your changes applied. This is how reviewers check your changes. +- If the Netlify build succeeds, select **Details** opens a staged version of + the OpenTelemetry website with your changes applied. This is how reviewers + check your changes. GitHub also automatically assigns labels to a PR to help reviewers. #### Changes from reviewers -Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits. +Sometimes reviewers commit to your pull request. Before making any other +changes, fetch those commits. 1. Fetch commits from your remote fork and rebase your working branch: @@ -399,7 +411,8 @@ create a merge conflict. You must resolve all merge conflicts in your PR. git push --force-with-lease origin ``` -1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and rebase your branch: +1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and + rebase your branch: ```shell git fetch upstream @@ -414,11 +427,11 @@ create a merge conflict. You must resolve all merge conflicts in your PR. This results in a number of files marked as conflicted. -1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. - Resolve the conflict and delete the conflict marker. +1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, + and `===`. Resolve the conflict and delete the conflict marker. - {{< note >}} - For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). + {{< note >}} For more information, see + [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). {{< /note >}} 1. Add the files to the changeset: @@ -435,7 +448,8 @@ create a merge conflict. You must resolve all merge conflicts in your PR. 1. Repeat steps 2 to 5 as needed. - After applying all commits, the `git status` command shows that the rebase is complete. + After applying all commits, the `git status` command shows that the rebase is + complete. 1. Force-push the branch to your fork: @@ -465,12 +479,13 @@ the templates with as much detail as possible when you file issues or PRs. ## Open an issue -If you want to suggest improvements to existing content or notice an error, -open an issue. +If you want to suggest improvements to existing content or notice an error, open +an issue. -1. Click the **Create documentation issue** link on the right sidebar. This redirects you - to a GitHub issue page prepopulated with some headers. -2. Describe the issue or suggestion for improvement. Provide as many details as you can. +1. Click the **Create documentation issue** link on the right sidebar. This + redirects you to a GitHub issue page prepopulated with some headers. +2. Describe the issue or suggestion for improvement. Provide as many details as + you can. 3. Click **Submit new issue**. After submitting, check in on your issue occasionally or turn on GitHub @@ -479,36 +494,37 @@ they can take action on your issue. ### Suggesting new content -If you have an idea for new content, but you aren't sure where it should go, -you can still file an issue. Either: +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/open-telemetry/opentelemetry.io/issues/new/) and file the issue directly. +- Choose an existing page in the section you think the content belongs in and + click **Create documentation issue**. +- Go to [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) + and file the issue directly. ## How to file great issues Keep the following in mind when filing an issue: -- Provide a clear issue description. Describe what specifically is missing, out of date, - wrong, or needs improvement. +- Provide a clear issue description. Describe what specifically is missing, out + of date, wrong, or needs improvement. - Explain the specific impact the issue has on users. - Limit the scope of a given issue to a reasonable unit of work. For problems - with a large scope, break them down into smaller issues. For example, "Fix the security docs" - is too broad, but "Add details to the 'Restricting network access' topic" is specific enough - to be actionable. -- Search the existing issues to see if there's anything related or similar to the - new issue. -- If the new issue relates to another issue or pull request, refer to it - either by its full URL or by the issue or pull request number prefixed - with a `#` character. For example, `Introduced by #987654`. -- Follow the [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). Respect your -fellow contributors. For example, "The docs are terrible" is not + with a large scope, break them down into smaller issues. For example, "Fix the + security docs" is too broad, but "Add details to the 'Restricting network + access' topic" is specific enough to be actionable. +- Search the existing issues to see if there's anything related or similar to + the new issue. +- If the new issue relates to another issue or pull request, refer to it either + by its full URL or by the issue or pull request number prefixed with a `#` + character. For example, `Introduced by #987654`. +- Follow the + [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). + Respect your fellow contributors. For example, "The docs are terrible" is not helpful or polite feedback. - ## Other ways to contribute - Visit the [OpenTelemetry community site](/community/). - Add your application to the [Registry](/ecosystem). - Submit a [blog post or case study](/docs/contribute/blogs-case-studies/). - diff --git a/content/en/docs/Contribute/blogs-case-studies.md b/content/en/docs/Contribute/blogs-case-studies.md index 7c855689b959..f05cb6fa1749 100644 --- a/content/en/docs/Contribute/blogs-case-studies.md +++ b/content/en/docs/Contribute/blogs-case-studies.md @@ -31,50 +31,54 @@ Unsuitable content includes: To submit a blog post, follow these steps: -1. [Sign the CLA](https://docs.linuxfoundation.org/lfx/easycla/contributors) - if you have not yet done so. +1. [Sign the CLA](https://docs.linuxfoundation.org/lfx/easycla/contributors) if + you have not yet done so. 1. Have a look at the Markdown format for existing blog posts in the [opentelemetry.io repository](https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/blog). 1. Write out your blog post in a text editor of your choice. -1. On the same link from step 2, select **Create new file**. Paste your content into the editor. - Name the file to match the proposed title of the blog post, but don’t put the date in the file name. - The blog reviewers will work with you on the final file name and the date the blog will be published. +1. On the same link from step 2, select **Create new file**. Paste your content + into the editor. Name the file to match the proposed title of the blog post, + but don’t put the date in the file name. The blog reviewers will work with + you on the final file name and the date the blog will be published. -1. When you save the file, GitHub will walk you through the pull request process. +1. When you save the file, GitHub will walk you through the pull request + process. -1. A blog post reviewer will review your submission and work with you on feedback and final details. - When the blog post is approved, the blog will be scheduled for publication. +1. A blog post reviewer will review your submission and work with you on + feedback and final details. When the blog post is approved, the blog will be + scheduled for publication. ## Guidelines and expectations -- Blog posts should not be vendor pitches. +- Blog posts should not be vendor pitches. - - Articles must contain content that applies broadly to the OpenTelemetry community. For example, a - submission should focus on upstream OpenTelemetry as opposed to vendor-specific configurations. - Check the [Documentation style guide](/docs/contribute/style/content-guide/#what-s-allowed) for - what is typically allowed on OpenTelemetry properties. - - Links should primarily be to the official OpenTelemetry documentation. When using external - references, links should be diverse - For example a submission shouldn't contain only links - back to a single company's blog. + - Articles must contain content that applies broadly to the OpenTelemetry + community. For example, a submission should focus on upstream OpenTelemetry + as opposed to vendor-specific configurations. + - Links should primarily be to the official OpenTelemetry documentation. When + using external references, links should be diverse - For example a + submission shouldn't contain only links back to a single company's blog. - Blog posts are not published on specific dates. - - Articles are reviewed by community volunteers. We'll try our best to accommodate specific - timing, but we make no guarantees. - - Many core parts of the OpenTelemetry projects submit blog posts during release windows, delaying - publication times. Consider submitting during a quieter period of the release cycle. - - If you are looking for greater coordination on post release dates, coordinating with - [CNCF marketing](https://www.cncf.io/about/contact/) is a more appropriate choice than submitting a blog post. + - Articles are reviewed by community volunteers. We'll try our best to + accommodate specific timing, but we make no guarantees. + - Many core parts of the OpenTelemetry projects submit blog posts during + release windows, delaying publication times. Consider submitting during a + quieter period of the release cycle. + - If you are looking for greater coordination on post release dates, + coordinating with [CNCF marketing](https://www.cncf.io/about/contact/) is a + more appropriate choice than submitting a blog post. - Blog posts should be relevant to OpenTelemetry users. - - Topics related to participation in or results of OpenTelemetry SIGs activities are always on - topic. - - Posts about other CNCF projects may or may not be on topic. We recommend asking the blog team - before submitting a draft. - - Many CNCF projects have their own blog. These are often a better choice for posts. There are - times of major feature or milestone for a CNCF project that users would be interested in - reading on the OpenTelemetry blog. + - Topics related to participation in or results of OpenTelemetry SIGs + activities are always on topic. + - Posts about other CNCF projects may or may not be on topic. We recommend + asking the blog team before submitting a draft. + - Many CNCF projects have their own blog. These are often a better choice for + posts. There are times of major feature or milestone for a CNCF project that + users would be interested in reading on the OpenTelemetry blog. diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index c6b0adf7bbb6..5379b6c2e3d1 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -6,669 +6,22 @@ cSpell:ignore: slug: style-guide --- -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 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 -or addition, [add it to the agenda](https://bit.ly/sig-docs-agenda) for an upcoming -SIG Docs meeting, and attend the meeting to participate in the discussion. - - - -{{< note >}} -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 -glossary entries, tabs, and representing feature state. -{{< /note >}} - -## Language - -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 OpenTelemetry Documentation](/docs/contribute/localization/). - -The English-language documentation uses U.S. English spelling and grammar. - -{{< comment >}}[If you're localizing this page, you can omit the point about US English.]{{< /comment >}} - -## Documentation formatting standards - -### Use upper camel case for API objects - -When you refer specifically to interacting with an API object, use -[UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), also known as -Pascal case. You may see different capitalization, such as "configMap", -in the [API Reference](/docs/reference/kubernetes-api/). When writing -general documentation, it's better to use upper camel case, calling it "ConfigMap" instead. - -When you are generally discussing an API object, use -[sentence-style capitalization](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization). - -The following examples focus on capitalization. For more information about formatting -API object names, review the related guidance on [Code Style](#code-style-inline-code). - -{{< table caption = "Do and Don't - Use Pascal case for API objects" >}} -Do | Don't -:--| :----- -The HorizontalPodAutoscaler resource is responsible for ... | The Horizontal pod autoscaler is responsible for ... -A PodList object is a list of pods. | A Pod List object is a list of pods. -The Volume object contains a `hostPath` field. | The volume object contains a hostPath field. -Every ConfigMap object is part of a namespace. | Every configMap object is part of a namespace. -For managing confidential data, consider using the Secret API. | For managing confidential data, consider using the secret API. -{{< /table >}} - -### Use angle brackets for placeholders - -Use angle brackets for placeholders. Tell the reader what a placeholder -represents, for example: - -Display information about a pod: - -```shell -kubectl describe pod -n -``` - -If the namespace of the pod is `default`, you can omit the '-n' parameter. - -### Use bold for user interface elements - -{{< table caption = "Do and Don't - Bold interface elements" >}} -Do | Don't -:--| :----- -Click **Fork**. | Click "Fork". -Select **Other**. | Select "Other". -{{< /table >}} - -### Use italics to define or introduce new terms - -{{< table caption = "Do and Don't - Use italics for new terms" >}} -Do | Don't -:--| :----- -A _cluster_ is a set of nodes ... | A "cluster" is a set of nodes ... -These components form the _control plane_. | These components form the **control plane**. -{{< /table >}} - -### Use code style for filenames, directories, and paths - -{{< table caption = "Do and Don't - Use code style for filenames, directories, and paths" >}} -Do | Don't -:--| :----- -Open the `envars.yaml` file. | Open the envars.yaml file. -Go to the `/docs/tutorials` directory. | Go to the /docs/tutorials directory. -Open the `/_data/concepts.yaml` file. | Open the /\_data/concepts.yaml file. -{{< /table >}} - -### Use the international standard for punctuation inside quotes - -{{< table caption = "Do and Don't - Use the international standard for punctuation inside quotes" >}} -Do | Don't -:--| :----- -events are recorded with an associated "stage". | events are recorded with an associated "stage." -The copy is called a "fork". | The copy is called a "fork." -{{< /table >}} - -## Inline code formatting - -### Use code style for inline code, commands, and API objects {#code-style-inline-code} - -For inline code in an HTML document, use the `` tag. In a Markdown -document, use the backtick (`` ` ``). - -{{< table caption = "Do and Don't - Use code style for inline code, commands, and API objects" >}} -Do | Don't -:--| :----- -The `kubectl run` command creates a `Pod`. | The "kubectl run" command creates a pod. -The kubelet on each node acquires a `Lease`… | The kubelet on each node acquires a lease… -A `PersistentVolume` represents durable storage… | A Persistent Volume represents durable storage… -For declarative management, use `kubectl apply`. | For declarative management, use "kubectl apply". -Enclose code samples with triple backticks. (\`\`\`)| Enclose code samples with any other syntax. -Use single backticks to enclose inline code. For example, `var example = true`. | Use two asterisks (`**`) or an underscore (`_`) to enclose inline code. For example, **var example = true**. -Use triple backticks before and after a multi-line block of code for fenced code blocks. | Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations. -Use meaningful variable names that have a context. | Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context. -Remove trailing spaces in the code. | Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well. -{{< /table >}} - -{{< note >}} -The website supports syntax highlighting for code samples, but specifying a language -is optional. Syntax highlighting in the code block should conform to the -[contrast guidelines.](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0&showtechniques=141%2C143#contrast-minimum) -{{< /note >}} - -### Use code style for object field names and namespaces - -{{< table caption = "Do and Don't - Use code style for object field names" >}} -Do | Don't -:--| :----- -Set the value of the `replicas` field in the configuration file. | Set the value of the "replicas" field in the configuration file. -The value of the `exec` field is an ExecAction object. | The value of the "exec" field is an ExecAction object. -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 OpenTelemetry 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. -The `kubectl` handles locating and authenticating to the API server. | The kubectl handles locating and authenticating to the apiserver. -Run the process with the certificate, `kube-apiserver --client-ca-file=FILENAME`. | Run the process with the certificate, kube-apiserver --client-ca-file=FILENAME. | -{{< /table >}} - -### Starting a sentence with a component tool or component name - -{{< table caption = "Do and Don't - Starting a sentence with a component tool or component name" >}} -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 OpenTelemetry. | kube-scheduler is the default scheduler for OpenTelemetry. -{{< /table >}} - -### Use a general descriptor over a component name - -{{< table caption = "Do and Don't - Use a general descriptor over a component name" >}} -Do | Don't -:--| :----- -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 >}} - -### Use normal style for string and integer field values - -For field values of type string or integer, use normal style without quotation marks. - -{{< table caption = "Do and Don't - Use normal style for string and integer field values" >}} -Do | Don't -:--| :----- -Set the value of `imagePullPolicy` to Always. | Set the value of `imagePullPolicy` to "Always". -Set the value of `image` to nginx:1.16. | Set the value of `image` to `nginx:1.16`. -Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`. -{{< /table >}} - -## Referring to OpenTelemetry API resources - -This section talks about how we reference API resources in the documentation. - -### Clarification about "resource" - -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 OpenTelemetry API terminologies - -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 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`". - -### API resource names - -Always format API resource names using [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), -also known as PascalCase, and code formatting. - -For inline code in an HTML document, use the `` tag. In a Markdown document, use the backtick (`` ` ``). - -Don't split an API object name into separate words. For example, use `PodTemplateList`, not Pod Template List. - -For more information about PascalCase and code formatting, please review the related guidance on -[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 OpenTelemetry API terminologies, please review the related -guidance on [OpenTelemetry API terminology](/docs/reference/using-api/api-concepts/#standard-api-terminology). - -## Code snippet formatting - -### Don't include the command prompt - -{{< table caption = "Do and Don't - Don't include the command prompt" >}} -Do | Don't -:--| :----- -kubectl get pods | $ kubectl get pods -{{< /table >}} - -### Separate commands from output - -Verify that the pod is running on your chosen node: - -```shell -kubectl get pods --output=wide -``` - -The output is similar to this: - -```console -NAME READY STATUS RESTARTS AGE IP NODE -nginx 1/1 Running 0 13s 10.200.0.4 worker0 -``` - -### 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 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 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 OpenTelemetry version 1.8, -the front-matter of your markdown file should look something like: - -```yaml ---- -title: -min-kubernetes-server-version: v1.8 ---- -``` - -In code and configuration examples, do not include comments about alternative versions. -Be careful to not include incorrect statements in your examples as comments, such as: - -```yaml -apiVersion: v1 # earlier versions use... -kind: Pod -... -``` +The OpenTelemetry documentation adheres to the +[Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) +and the +[Google Developer Documentation Style Guide](https://developers.google.com/style) +. The following sections contain guidance that is specific to the OpenTelemetry +project. ## OpenTelemetry.io word list -A list of OpenTelemetry-specific terms and words to be used consistently across the site. - -{{< table caption = "OpenTelemetry.io word list" >}} -Term | Usage -:--- | :---- -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. -{{< /table >}} - -## Shortcodes - -Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create -different rhetorical appeal levels. Our documentation supports three different -shortcodes in this category: **Note** `{{}}`, -**Caution** `{{}}`, and **Warning** `{{}}`. - -1. Surround the text with an opening and closing shortcode. - -2. Use the following syntax to apply a style: - - ```none - {{}} - No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.) - {{}} - ``` - - The output is: - - {{< note >}} - The prefix you choose is the same text for the tag. - {{< /note >}} - -### Note - -Use `{{}}` to highlight a tip or a piece of information that may be helpful to know. - -For example: - -``` -{{}} -You can _still_ use Markdown inside these callouts. -{{}} -``` - -The output is: - -{{< note >}} -You can _still_ use Markdown inside these callouts. -{{< /note >}} - -You can use a `{{}}` in a list: - -``` -1. Use the note shortcode in a list - -1. A second item with an embedded note - - {{}} - Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues). - {{}} - -1. A third item in a list - -1. A fourth item in a list -``` - -The output is: - -1. Use the note shortcode in a list - -1. A second item with an embedded note - - {{< note >}} - Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues). - {{< /note >}} - -1. A third item in a list - -1. A fourth item in a list - -### Caution - -Use `{{}}` to call attention to an important piece of information to avoid pitfalls. - -For example: - -``` -{{}} -The callout style only applies to the line directly above the tag. -{{}} -``` - -The output is: - -{{< caution >}} -The callout style only applies to the line directly above the tag. -{{< /caution >}} - -### Warning - -Use `{{}}` to indicate danger or a piece of information that is crucial to follow. - -For example: - -``` -{{}} -Beware. -{{}} -``` - -The output is: - -{{< warning >}} -Beware. -{{< /warning >}} - -## Common Shortcode Issues - -### Ordered Lists - -Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag. - -For example: - - 1. Preheat oven to 350˚F - - 1. Prepare the batter, and pour into springform pan. - {{}}Grease the pan for best results.{{}} - - 1. Bake for 20-25 minutes or until set. - -The output is: - -1. Preheat oven to 350˚F - -1. Prepare the batter, and pour into springform pan. - - {{< note >}}Grease the pan for best results.{{< /note >}} - -1. Bake for 20-25 minutes or until set. - -### Include Statements - -Shortcodes inside include statements will break the build. You must insert them -in the parent document, before and after you call the include. For example: - -``` -{{}} -{{}} -{{}} -``` - -## Markdown elements - -### Line breaks - -Use a single newline to separate block-level content like headings, lists, images, -code blocks, and others. The exception is second-level headings, where it should -be two newlines. Second-level headings follow the first-level (or the title) without -any preceding paragraphs or texts. A two line spacing helps visualize the overall -structure of content in a code editor better. - -Manually wrap paragraphs in the Markdown source when appropriate. Since the git -tool and the GitHub website generate file diffs on a line-by-line basis, -manually wrapping long lines helps the reviewers to easily find out the changes -made in a PR and provide feedback. It also helps the downstream localization -teams where people track the upstream changes on a per-line basis. Line -wrapping can happen at the end of a sentence or a punctuation character, for -example. One exception to this is that a Markdown link or a shortcode is -expected to be in a single line. - -### Headings and titles {#headings} - -People accessing this documentation may use a screen reader or other assistive technology (AT). -[Screen readers](https://en.wikipedia.org/wiki/Screen_reader) are linear output devices, -they output items on a page one at a time. If there is a lot of content on a page, you can -use headings to give the page an internal structure. A good page structure helps all readers -to easily navigate the page or filter topics of interest. - -{{< table caption = "Do and Don't - Headings" >}} -Do | Don't -:--| :----- -Update the title in the front matter of the page or blog post. | Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading. -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: 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 - -{{< table caption = "Do and Don't - Paragraphs" >}} -Do | Don't -:--| :----- -Try to keep paragraphs under 6 sentences. | Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it. -Use three hyphens (`---`) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section. | Use horizontal rules for decoration. -{{< /table >}} - -### Links - -{{< table caption = "Do and Don't - Links" >}} -Do | Don't -:--| :----- -Write hyperlinks that give you context for the content they link to. For example: Certain ports are open on your machines. See Check required ports for more details. | Use ambiguous terms such as "click here". For example: Certain ports are open on your machines. See here for more details. -Write Markdown-style links: `[link text](URL)`. For example: `[Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions)` and the output is [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions). | Write HTML-style links: `Visit our tutorial!`, or create links that open in new tabs or windows. For example: `[example website](https://example.com){target="_blank"}` -{{< /table >}} - -### Lists - -Group items in a list that are related to each other and need to appear in a specific -order or to indicate a correlation between multiple items. When a screen reader comes -across a list—whether it is an ordered or unordered list—it will be announced to the -user that there is a group of list items. The user can then use the arrow keys to move -up and down between the various items in the list. Website navigation links can also be -marked up as list items; after all they are nothing but a group of related links. - -- End each item in a list with a period if one or more items in the list are complete - sentences. For the sake of consistency, normally either all items or none should be complete sentences. - - {{< note >}} - Ordered lists that are part of an incomplete introductory sentence can be in lowercase - and punctuated as if each item was a part of the introductory sentence. - {{< /note >}} - -- Use the number one (`1.`) for ordered lists. - -- Use (`+`), (`*`), or (`-`) for unordered lists. - -- Leave a blank line after each list. - -- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅). - -- List items may consist of multiple paragraphs. Each subsequent paragraph in a list - item must be indented by either four spaces or one tab. - -### Tables - -The semantic purpose of a data table is to present tabular data. Sighted users can -quickly scan the table but a screen reader goes through line by line. A table caption -is used to create a descriptive title for a data table. Assistive technologies (AT) -use the HTML table caption element to identify the table contents to the user within the page structure. - -- Add table captions using [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions) for tables. - -## Content best practices - -This section contains suggested best practices for clear, concise, and consistent content. - -### Use present tense - -{{< table caption = "Do and Don't - Use present tense" >}} -Do | Don't -:--| :----- -This command starts a proxy. | This command will start a proxy. - {{< /table >}} - -Exception: Use future or past tense if it is required to convey the correct -meaning. - -### Use active voice - -{{< table caption = "Do and Don't - Use active voice" >}} -Do | Don't -:--| :----- -You can explore the API using a browser. | The API can be explored using a browser. -The YAML file specifies the replica count. | The replica count is specified in the YAML file. -{{< /table >}} - -Exception: Use passive voice if active voice leads to an awkward construction. - -### Use simple and direct language - -Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." - -{{< table caption = "Do and Don't - Use simple and direct language" >}} -Do | Don't -:--| :----- -To create a ReplicaSet, ... | In order to create a ReplicaSet, ... -See the configuration file. | Please see the configuration file. -View the pods. | With this next command, we'll view the pods. -{{< /table >}} - -### Address the reader as "you" - -{{< table caption = "Do and Don't - Addressing the reader" >}} -Do | Don't -:--| :----- -You can create a Deployment by ... | We'll create a Deployment by ... -In the preceding output, you can see... | In the preceding output, we can see ... -{{< /table >}} - -### Avoid Latin phrases - -Prefer English terms over Latin abbreviations. - -{{< table caption = "Do and Don't - Avoid Latin phrases" >}} -Do | Don't -:--| :----- -For example, ... | e.g., ... -That is, ...| i.e., ... -{{< /table >}} - -Exception: Use "etc." for et cetera. - -## Patterns to avoid - -### Avoid using "we" - -Using "we" in a sentence can be confusing, because the reader might not know -whether they're part of the "we" you're describing. - -{{< table caption = "Do and Don't - Patterns to avoid" >}} -Do | Don't -:--| :----- -Version 1.4 includes ... | In version 1.4, we have added ... -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 >}} - -### Avoid jargon and idioms - -Some readers speak English as a second language. Avoid jargon and idioms to help them understand better. - -{{< table caption = "Do and Don't - Avoid jargon and idioms" >}} -Do | Don't -:--| :----- -Internally, ... | Under the hood, ... -Create a new cluster. | Turn up a new cluster. -{{< /table >}} - -### Avoid statements about the future - -Avoid making promises or giving hints about the future. If you need to talk about -an alpha feature, put the text under a heading that identifies it as alpha -information. - -An exception to this rule is documentation about announced deprecations -targeting removal in future versions. One example of documentation like this -is the [Deprecated API migration guide](/docs/reference/using-api/deprecation-guide/). - -### Avoid statements that will soon be out of date - -Avoid words like "currently" and "new." A feature that is new today might not be -considered new in a few months. - -{{< table caption = "Do and Don't - Avoid statements that will soon be out of date" >}} -Do | Don't -:--| :----- -In version 1.4, ... | In the current version, ... -The Federation feature provides ... | The new Federation feature provides ... -{{< /table >}} - -### Avoid words that assume a specific level of understanding - -Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value. - -{{< table caption = "Do and Don't - Avoid insensitive words" >}} -Do | Don't -:--| :----- -Include one command in ... | Include just one command in ... -Run the container ... | Simply run the container ... -You can remove ... | You can easily remove ... -These steps ... | These simple steps ... -{{< /table >}} - -### EditorConfig file -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/open-telemetry/opentelemetry.io/blob/main/.editorconfig) in the repository root. - -## {{% heading "whatsnext" %}} +A list of OpenTelemetry-specific terms and words to be used consistently across +the site. -* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/). -* Learn about [using page templates](/docs/contribute/style/page-content-types/). -* Learn about [custom hugo shortcodes](/docs/contribute/style/hugo-shortcodes/). -* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/). + +| Term | Usage | +| --- | --- | +| OpenTelemetry | OpenTelemetry should always be capitalized. | +| OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. | +| Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. | + From 228421494a1c42d389da6c6611a737fc6f79f8dd Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Mon, 11 Dec 2023 17:27:27 +0100 Subject: [PATCH 08/62] More fixes --- content/en/docs/Contribute/style-guide.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index 5379b6c2e3d1..2787a68ad822 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -25,3 +25,6 @@ the site. | OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. | | Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. | + +See also the [Glossary](/docs/concepts/glossary/) for a list of OpenTelemetry +terms and their definition. \ No newline at end of file From 7b004b035d9231cd34ab88ee9b3e570629865436 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 12 Dec 2023 10:00:08 +0100 Subject: [PATCH 09/62] Fix linter issues --- content/en/docs/Contribute/_index.md | 30 ++++++------- .../en/docs/Contribute/blogs-case-studies.md | 4 +- content/en/docs/Contribute/style-guide.md | 9 ++-- static/refcache.json | 44 +++++++++++++++++++ 4 files changed, 65 insertions(+), 22 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 8ccc13bbf113..abe159372a8d 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -2,12 +2,12 @@ title: Contribute description: Learn how to contribute to the OpenTelemetry documentation. weight: 200 -cSpell:ignore: +cSpell:ignore: spacewhite prepopulated linktitle open-telemetry repos --- You can open an issue about OpenTelemetry documentation, or contribute a change with a pull request (PR) to the -[`open-telemetry/opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). +[`opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). OpenTelemetry documentation contributors: @@ -25,8 +25,8 @@ Conduct. To contribute, you need to be familiar with the following techs and tools: -- [git](https://git-scm.com/) -- [GitHub](https://lab.github.com/) +- git +- GitHub - Markdown (CommonMark) - YAML @@ -184,10 +184,10 @@ class changes,changes2 white Figure 2. Working from a local fork to make your changes. -#### Fork the open-telemetry/opentelemetry.io repository +#### Fork the opentelemetry.io repository 1. Navigate to the - [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) + [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) repository. 1. Select **Fork**. @@ -311,14 +311,13 @@ close the terminal window. #### Open a pull request from your fork {#open-a-pr} Figure 3 shows the steps to open a PR from your fork to the -[open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) -. +[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) . ```mermaid flowchart LR subgraph first[ ] direction TB -1[1. Go to open-telemetry/opentelemetry.io repository] --> 2[2. Select New Pull Request] +1[1. Go to opentelemetry.io repository] --> 2[2. Select New Pull Request] 2 --> 3[3. Select compare across forks] 3 --> 4[4. Select your fork from
head repository drop-down menu] end @@ -338,10 +337,10 @@ class first,second white ``` Figure 3. Steps to open a PR from your fork to the -[open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). +[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). 1. In a web browser, go to the - [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) + [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) repository. 1. Select **New Pull Request**. 1. Select **compare across forks**. @@ -430,9 +429,8 @@ create a merge conflict. You must resolve all merge conflicts in your PR. 1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. Resolve the conflict and delete the conflict marker. - {{< note >}} For more information, see + For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). - {{< /note >}} 1. Add the files to the changeset: @@ -461,9 +459,9 @@ create a merge conflict. You must resolve all merge conflicts in your PR. ## Contribute to other repos -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. +The OpenTelemetry project contains many repositories. Many of these repositories +contain documentation: user-facing help text, error messages, API references or +code comments. If you see text you'd like to improve, use GitHub to search all repositories in the OpenTelemetry organization. This can help you figure out where to submit diff --git a/content/en/docs/Contribute/blogs-case-studies.md b/content/en/docs/Contribute/blogs-case-studies.md index f05cb6fa1749..5f08e2456ac7 100644 --- a/content/en/docs/Contribute/blogs-case-studies.md +++ b/content/en/docs/Contribute/blogs-case-studies.md @@ -1,9 +1,9 @@ --- title: Submit a blog post -linktitle: Submit a blog post +linkTitle: Submit a blog post slug: blogs-case-studies weight: 30 -cSpell:ignore: +cSpell:ignore: open-telemetry --- The [OpenTelemetry blog](/blog/) communicates new features, community reports, diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index 2787a68ad822..1756d819705a 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -1,9 +1,9 @@ --- title: Documentation style guide -linktitle: Style guide +linkTitle: Style guide weight: 40 cSpell:ignore: -slug: style-guide +slug: style-guide open-telemetry --- The OpenTelemetry documentation adheres to the @@ -21,10 +21,11 @@ the site. | Term | Usage | | --- | --- | -| OpenTelemetry | OpenTelemetry should always be capitalized. | +| OpenTelemetry | OpenTelemetry should always be capitalized. Don't use Open-Telemetry. | | OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. | | Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. | +| Repository | Code repositories. Don't use repo or repos. | See also the [Glossary](/docs/concepts/glossary/) for a list of OpenTelemetry -terms and their definition. \ No newline at end of file +terms and their definition. diff --git a/static/refcache.json b/static/refcache.json index 7b9d63b7cb63..c444263b9655 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -719,6 +719,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T15:51:20.598962-04:00" }, + "https://developers.google.com/style": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:04:54.694842+01:00" + }, "https://devstats.cncf.io/": { "StatusCode": 206, "LastSeen": "2023-06-29T16:21:23.471592-04:00" @@ -1083,6 +1087,10 @@ "StatusCode": 206, "LastSeen": "2023-09-15T16:58:35.759747+02:00" }, + "https://docs.linuxfoundation.org/lfx/easycla/contributors": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:05:05.806034+01:00" + }, "https://docs.locust.io/en/stable/writing-a-locustfile.html": { "StatusCode": 200, "LastSeen": "2023-06-29T15:47:17.793642-04:00" @@ -1923,6 +1931,18 @@ "StatusCode": 200, "LastSeen": "2023-06-29T16:04:43.002783-04:00" }, + "https://git-scm.com/": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:04:54.723883+01:00" + }, + "https://git-scm.com/book/en/v2/Getting-Started-Installing-Git": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:05.965228+01:00" + }, + "https://git-scm.com/docs/git-merge#_how_conflicts_are_presented": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:07.954292+01:00" + }, "https://github.blog/2021-05-26-why-and-how-github-is-adopting-opentelemetry/": { "StatusCode": 200, "LastSeen": "2023-06-30T16:26:22.927158-04:00" @@ -3631,6 +3651,10 @@ "StatusCode": 200, "LastSeen": "2023-06-30T08:48:34.579016-04:00" }, + "https://github.com/open-telemetry/opentelemetry.io": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:04:54.562763+01:00" + }, "https://github.com/open-telemetry/opentelemetry.io#adding-a-project-to-the-opentelemetry-registry": { "StatusCode": 200, "LastSeen": "2023-06-30T08:46:35.260059-04:00" @@ -3643,6 +3667,10 @@ "StatusCode": 200, "LastSeen": "2023-09-08T10:57:01.381266-04:00" }, + "https://github.com/open-telemetry/opentelemetry.io/": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:06.564186+01:00" + }, "https://github.com/open-telemetry/opentelemetry.io/issues/new": { "StatusCode": 200, "LastSeen": "2023-06-30T08:31:06.342368-04:00" @@ -3659,6 +3687,10 @@ "StatusCode": 200, "LastSeen": "2023-09-12T11:57:04.702626-04:00" }, + "https://github.com/open-telemetry/opentelemetry.io/pulls": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:07.270135+01:00" + }, "https://github.com/open-telemetry/otel-arrow": { "StatusCode": 200, "LastSeen": "2023-11-14T11:45:08.675719+01:00" @@ -4451,6 +4483,10 @@ "StatusCode": 206, "LastSeen": "2023-07-28T12:17:39.145108-04:00" }, + "https://kubernetes.io/docs/contribute/style/style-guide/": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:04:54.259484+01:00" + }, "https://kubernetes.io/docs/reference/kubectl/": { "StatusCode": 206, "LastSeen": "2023-06-30T11:49:31.853471-04:00" @@ -5999,6 +6035,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T18:48:57.135457-04:00" }, + "https://www.cncf.io/about/contact/": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:05:06.564168+01:00" + }, "https://www.cncf.io/blog/2019/05/21/a-brief-history-of-opentelemetry-so-far/": { "StatusCode": 206, "LastSeen": "2023-06-30T09:22:37.957195-04:00" @@ -6359,6 +6399,10 @@ "StatusCode": 206, "LastSeen": "2023-10-16T20:09:59.62173+02:00" }, + "https://www.netlify.com/": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:05:07.468279+01:00" + }, "https://www.nomadproject.io": { "StatusCode": 206, "LastSeen": "2023-06-30T08:50:51.721695-04:00" From 040fe94053f823b25650d26012eb2e760f20c9de Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 12 Dec 2023 10:04:06 +0100 Subject: [PATCH 10/62] Fix terminology error --- content/en/docs/Contribute/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index abe159372a8d..f60b465ce730 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -457,7 +457,7 @@ create a merge conflict. You must resolve all merge conflicts in your PR. The pull request no longer shows any conflicts. -## Contribute to other repos +## Contribute to other repositories The OpenTelemetry project contains many repositories. Many of these repositories contain documentation: user-facing help text, error messages, API references or From 83cd540a7ee0c61dc7a65012cf31b9f39f302257 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 12 Dec 2023 10:06:05 +0100 Subject: [PATCH 11/62] Linter fixes --- content/en/docs/Contribute/_index.md | 2 +- content/en/docs/Contribute/style-guide.md | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index f60b465ce730..8fb53c3b0177 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -2,7 +2,7 @@ title: Contribute description: Learn how to contribute to the OpenTelemetry documentation. weight: 200 -cSpell:ignore: spacewhite prepopulated linktitle open-telemetry repos +cSpell:ignore: linktitle open-telemetry prepopulated repos spacewhite --- You can open an issue about OpenTelemetry documentation, or contribute a change diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index 1756d819705a..11b68aafea15 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -2,7 +2,6 @@ title: Documentation style guide linkTitle: Style guide weight: 40 -cSpell:ignore: slug: style-guide open-telemetry --- From f4a2354ecd73ba257b9a6a1b4b6bb0ae0b8d012c Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:02:26 +0100 Subject: [PATCH 12/62] Update content/en/docs/Contribute/_index.md Co-authored-by: Severin Neumann --- content/en/docs/Contribute/_index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 8fb53c3b0177..b3919f29fc4b 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -132,8 +132,7 @@ Figure 1. Steps for opening a PR using GitHub. 1. Select **Create pull request**. Before merging a pull request, OpenTelemetry community members review and -approve it. If you have someone in mind, leave a comment with their GitHub -username in it. +approve it. If a reviewer asks you to make changes: From 74ac067959134df6f7f5811d54c5561680357ae6 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:02:34 +0100 Subject: [PATCH 13/62] Update content/en/docs/Contribute/_index.md Co-authored-by: Severin Neumann --- content/en/docs/Contribute/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index b3919f29fc4b..0e2d58cda37f 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -25,9 +25,9 @@ Conduct. To contribute, you need to be familiar with the following techs and tools: -- git -- GitHub -- Markdown (CommonMark) +- [git](https://git-scm.com/) +- [GitHub](https://github.com/) +- Markdown ([CommonMark](https://commonmark.org/)) - YAML For technical details concerning how the documentation is built and tested From 25ecb76ea314c749e82baf04b22862c004eaa315 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:03:00 +0100 Subject: [PATCH 14/62] Update content/en/docs/Contribute/_index.md Co-authored-by: Severin Neumann --- content/en/docs/Contribute/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 0e2d58cda37f..1c392ae218a7 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -141,7 +141,7 @@ If a reviewer asks you to make changes: 1. Make the changes requested. 1. Commit the changes. -When your review is complete, a reviewer merges your PR and your changes go liv +When your review is complete, a reviewer merges your PR and your changes goes live a few minutes later. ### Work from a local fork {#fork-the-repo} From 6bfac8bb2d648a64f5634d5f1b361cd3d8ab5a22 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:09:18 +0100 Subject: [PATCH 15/62] Edit --- content/en/docs/Contribute/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 8fb53c3b0177..beb6e2206c43 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -459,9 +459,9 @@ create a merge conflict. You must resolve all merge conflicts in your PR. ## Contribute to other repositories -The OpenTelemetry project contains many repositories. Many of these repositories -contain documentation: user-facing help text, error messages, API references or -code comments. +The OpenTelemetry project contains many repositories. Several of these +repositories contain documentation: user-facing help text, error messages, API +references or code comments. If you see text you'd like to improve, use GitHub to search all repositories in the OpenTelemetry organization. This can help you figure out where to submit From 36cede91ed3d493eb808fafd477a173aa9e640b6 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:14:14 +0100 Subject: [PATCH 16/62] Change casing --- content/en/docs/{Contribute => contribute}/_index.md | 0 content/en/docs/{Contribute => contribute}/acknowledgements.md | 0 content/en/docs/{Contribute => contribute}/blogs-case-studies.md | 0 content/en/docs/{Contribute => contribute}/style-guide.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename content/en/docs/{Contribute => contribute}/_index.md (100%) rename content/en/docs/{Contribute => contribute}/acknowledgements.md (100%) rename content/en/docs/{Contribute => contribute}/blogs-case-studies.md (100%) rename content/en/docs/{Contribute => contribute}/style-guide.md (100%) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/contribute/_index.md similarity index 100% rename from content/en/docs/Contribute/_index.md rename to content/en/docs/contribute/_index.md diff --git a/content/en/docs/Contribute/acknowledgements.md b/content/en/docs/contribute/acknowledgements.md similarity index 100% rename from content/en/docs/Contribute/acknowledgements.md rename to content/en/docs/contribute/acknowledgements.md diff --git a/content/en/docs/Contribute/blogs-case-studies.md b/content/en/docs/contribute/blogs-case-studies.md similarity index 100% rename from content/en/docs/Contribute/blogs-case-studies.md rename to content/en/docs/contribute/blogs-case-studies.md diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/contribute/style-guide.md similarity index 100% rename from content/en/docs/Contribute/style-guide.md rename to content/en/docs/contribute/style-guide.md From c9199c60e1ac7e7906e54818b275fa49f347aaee Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:48:24 +0100 Subject: [PATCH 17/62] Halfway peer edits --- content/en/docs/contribute/_index.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 2117fe3e22df..0c24220c9228 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -55,9 +55,10 @@ flowchart LR subgraph first[How to contribute] direction TB T[ ] -.- - A[Sign the CNCF CLA] --> D[Write docs in markdown
and build site with Hugo] - D[Write docs in markdown
and build site with Hugo] --- E[Push source to GitHub] - E --- G[Open a pull request] + B[Fork the repo in GitHub] --- C[Write docs in markdown
and build site with Hugo] + C --- D[Push source to the fork] + D --- E[Open a pull request] + E --- F[Sign the CNCF CLA] end classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; @@ -118,6 +119,8 @@ Figure 1. Steps for opening a PR using GitHub. 1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. +1. If you're not a member of the project, GitHub will offer to create a fork of the repository. Select **Fork this repository**. + 1. Make your changes in the GitHub editor. 1. Below the editor, fill in the **Propose file change** form. @@ -138,7 +141,7 @@ If a reviewer asks you to make changes: 1. Go to the **Files changed** tab. 1. Select the pencil (edit) icon on any files changed by the pull request. -1. Make the changes requested. +1. Make the changes requested. If there's a code suggestion, apply it. 1. Commit the changes. When your review is complete, a reviewer merges your PR and your changes goes live @@ -231,7 +234,8 @@ Figure 2. Working from a local fork to make your changes. ``` This makes sure your local repository is up to date before you start making - changes. + changes. Push changes from upstream to origin regularly to keep you fork in + sync with upstream. #### Create a branch @@ -290,6 +294,8 @@ When you are ready to submit a pull request, commit your changes. git push origin ``` +1. Once the changes are pushed, GitHub lets you know that you can create a PR. + #### Preview your changes locally {#preview-locally} Preview your changes locally before pushing them or opening a pull request. A @@ -371,6 +377,13 @@ using [Netlify](https://www.netlify.com/). the OpenTelemetry website with your changes applied. This is how reviewers check your changes. +Other checks might also fail, including: + +- File name checks +- Links resolution +- Markdown formatting +- Spelling + GitHub also automatically assigns labels to a PR to help reviewers. #### Changes from reviewers @@ -391,6 +404,8 @@ changes, fetch those commits. git push --force-with-lease origin ``` +You can also solve merge conflicts from the GitHub UI. + #### Merge conflicts and rebasing If another contributor commits changes to the same file in another PR, it can From c66b57929df323b1f9e6c02a60a8925fb6c8d235 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 14:55:32 +0100 Subject: [PATCH 18/62] Further edits --- content/en/docs/contribute/_index.md | 72 +++++++++++++---------- content/en/docs/contribute/style-guide.md | 11 +++- 2 files changed, 50 insertions(+), 33 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 0c24220c9228..6b1a67e38312 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -119,7 +119,8 @@ Figure 1. Steps for opening a PR using GitHub. 1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. -1. If you're not a member of the project, GitHub will offer to create a fork of the repository. Select **Fork this repository**. +1. If you're not a member of the project, GitHub will offer to create a fork of + the repository. Select **Fork this repository**. 1. Make your changes in the GitHub editor. @@ -144,8 +145,8 @@ If a reviewer asks you to make changes: 1. Make the changes requested. If there's a code suggestion, apply it. 1. Commit the changes. -When your review is complete, a reviewer merges your PR and your changes goes live -a few minutes later. +When your review is complete, a reviewer merges your PR and your changes goes +live a few minutes later. ### Work from a local fork {#fork-the-repo} @@ -471,48 +472,37 @@ create a merge conflict. You must resolve all merge conflicts in your PR. The pull request no longer shows any conflicts. -## Contribute to other repositories - -The OpenTelemetry project contains many repositories. Several of these -repositories contain documentation: user-facing help text, error messages, API -references or code comments. - -If you see text you'd like to improve, use GitHub to search all repositories in -the OpenTelemetry organization. This can help you figure out where to submit -your issue or PR. - -Each repository has its own processes and procedures. Before you file an issue -or submit a PR, read that repository's `README.md`, `CONTRIBUTING.md`, and -`code-of-conduct.md`, if they exist. - -Most repositories use issue and PR templates. Have a look through some open -issues and PRs to get a feel for that team's processes. Make sure to fill out -the templates with as much detail as possible when you file issues or PRs. - ## Open an issue If you want to suggest improvements to existing content or notice an error, open an issue. -1. Click the **Create documentation issue** link on the right sidebar. This - redirects you to a GitHub issue page prepopulated with some headers. +1. Click the **Create documentation issue** link on any document. This redirects + you to a GitHub issue page prepopulated with some headers. 2. Describe the issue or suggestion for improvement. Provide as many details as you can. 3. Click **Submit new issue**. After submitting, check in on your issue occasionally or turn on GitHub -notifications. Reviewers and other community members might ask questions before -they can take action on your issue. +notifications. It might take a few days until maintainers and approvers respond. +Reviewers and other community members might ask questions before they can take +action on your issue. + +### Suggesting new content or features + +If you have an idea for new content or a feature, but you aren't sure where it +should go, you can still file an issue. You can also report bugs and security +vulnerabilities. -### Suggesting new content +1. Go to + [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) and + select **New issue** inside the **Issues** tab. -If you have an idea for new content, but you aren't sure where it should go, you -can still file an issue. Either: +1. Select the type of issue that best applies to your request or doubt. -- Choose an existing page in the section you think the content belongs in and - click **Create documentation issue**. -- Go to [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) - and file the issue directly. +1. Fill out the template. + +1. Submit the issue. ## How to file great issues @@ -535,6 +525,24 @@ Keep the following in mind when filing an issue: Respect your fellow contributors. For example, "The docs are terrible" is not helpful or polite feedback. +## Contribute to other repositories + +The OpenTelemetry project contains many repositories. Several of these +repositories contain documentation: user-facing help text, error messages, API +references or code comments. + +If you see text you'd like to improve, use GitHub to search all repositories in +the OpenTelemetry organization. This can help you figure out where to submit +your issue or PR. + +Each repository has its own processes and procedures. Before you file an issue +or submit a PR, read that repository's `README.md`, `CONTRIBUTING.md`, and +`code-of-conduct.md`, if they exist. + +Most repositories use issue and PR templates. Have a look through some open +issues and PRs to get a feel for that team's processes. Make sure to fill out +the templates with as much detail as possible when you file issues or PRs. + ## Other ways to contribute - Visit the [OpenTelemetry community site](/community/). diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contribute/style-guide.md index 11b68aafea15..d018dcf90b1b 100644 --- a/content/en/docs/contribute/style-guide.md +++ b/content/en/docs/contribute/style-guide.md @@ -23,8 +23,17 @@ the site. | OpenTelemetry | OpenTelemetry should always be capitalized. Don't use Open-Telemetry. | | OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. | | Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. | -| Repository | Code repositories. Don't use repo or repos. | +| Repository | Code repository, lowercase when in the middle of a sentence. Don't use "repo" or "repos". | +| OTEP | OpenTelemetry Enhancement Proposal. Write "OTEPs" as plural form. Don't write "OTep" or "otep". | +| OpAMP | Open Agent Management Protocol. Don't write "OPAMP" or "opamp" in descriptions or instructions. | +| OTLP | OpenTelemetry Protocol. Don't write "OTlP" or "otlp" in descriptions or instructions. | +Make sure that proper nouns, such as other CNCF projects or third-party tools, +are properly written and use the original capitalization. For example, write +"PostgreSQL" instead of "postgre". For a full list, check the +[`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml) +file. + See also the [Glossary](/docs/concepts/glossary/) for a list of OpenTelemetry terms and their definition. From fdc5b29529716d5531b908cf51243950853eba71 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 14:58:03 +0100 Subject: [PATCH 19/62] Glossary entries --- content/en/docs/contribute/style-guide.md | 2 +- static/refcache.json | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contribute/style-guide.md index d018dcf90b1b..6b7a9daadc5e 100644 --- a/content/en/docs/contribute/style-guide.md +++ b/content/en/docs/contribute/style-guide.md @@ -2,7 +2,7 @@ title: Documentation style guide linkTitle: Style guide weight: 40 -slug: style-guide open-telemetry +slug: style-guide open-telemetry postgre textlintrc --- The OpenTelemetry documentation adheres to the diff --git a/static/refcache.json b/static/refcache.json index c444263b9655..5321c99c9588 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -475,6 +475,10 @@ "StatusCode": 200, "LastSeen": "2023-10-01T12:48:08.791661-04:00" }, + "https://commonmark.org/": { + "StatusCode": 206, + "LastSeen": "2023-12-13T14:56:57.912039+01:00" + }, "https://community.cncf.io/end-user-community/": { "StatusCode": 200, "LastSeen": "2023-07-03T17:44:06.5954165Z" @@ -1951,6 +1955,10 @@ "StatusCode": 200, "LastSeen": "2023-06-30T08:49:02.328002-04:00" }, + "https://github.com/": { + "StatusCode": 200, + "LastSeen": "2023-12-13T14:56:57.330463+01:00" + }, "https://github.com/Aneurysm9": { "StatusCode": 200, "LastSeen": "2023-06-30T09:32:40.687601-04:00" From 23db51dd8dabff9aeccb2f30ceea1d916beef7a4 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 16:06:15 +0100 Subject: [PATCH 20/62] Final edits --- CONTRIBUTING.md | 167 +++++------------- content/en/docs/contribute/_index.md | 104 +++++++++-- .../en/docs/contribute/blogs-case-studies.md | 116 +++++++----- content/en/docs/contribute/style-guide.md | 2 +- static/refcache.json | 16 ++ 5 files changed, 215 insertions(+), 190 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94a3bcf27a6e..525e46759b6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,46 +1,53 @@ # Contributing to OpenTelemetry.io -Thanks for your interest in contributing to -[OpenTelemetry.io](https://opentelemetry.io/)! Here are a few general guidelines -on contributing and reporting bugs that we ask you to review. Following these -guidelines helps to communicate that you respect the time of the contributors -managing and developing this open source project. In return, they should -reciprocate that respect in addressing your issue, assessing changes, and -helping you finalize your pull requests. In that spirit of mutual respect, we -endeavor to review incoming issues and pull requests, and will close any -lingering issues or pull requests after long times of inactivity. - -Note that all of your interactions in the project are subject to our -[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). -This includes creation of issues or pull requests, commenting on issues or pull -requests, and extends to all interactions in any real-time space e.g., Slack, -Discord, etc. - -Also review the general +**Thanks for your interest in contributing to +[OpenTelemetry.io](https://opentelemetry.io/)!** + +Follow these guidelines helps to communicate that you respect the time of the +contributors managing and developing this open source project. In return, +maintainers and approvers should reciprocate that respect in addressing your +issue, assessing changes, and helping you finalize your pull requests. In that +spirit of mutual respect, we endeavor to review incoming issues and pull +requests, and will close any lingering issues or pull requests after long times +of inactivity. + +## Before you get started + +### Code of Conduct + +All of your interactions in this project are subject to our +[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md) +. This includes the creation of issues or pull requests, commenting on issues or +pull requests, and extends to all interactions in any real-time space, for +example Slack, Discord, and so on. + +### Contributor License Agreement + +Review the general [OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md), -that will provide additional details, especially that you need to sign a +as it provides additional details, especially that you need to sign a Contributor License Agreement (CLA) before you can contribute. -## Found a security issue? +### Found a security issue? -If you discover a security issue, **do not** report it through GitHub. Instead, -follow the steps in our -[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy). +If you discover a security issue, read the +[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy) +before opening an issue. -## Found a problem? +### Found a problem? -If you find a problem with the content of this repository, or you would like to -request an enhancement, [create an issue][new-issue]. +If you find a bug or a problem with the content of this repository, or you would +like to request an enhancement, [create an issue][new-issue]. -Before reporting a new issue, please ensure that the issue was not already -reported or fixed by searching through our +Before reporting a new issue, make sure that the issue was not already reported +or fixed by searching through our [issues list](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc). -When creating a new issue, include a short meaningful title and clear a -description, as much relevant information as possible, and, if possible, a test -case. +When creating a new issue, include a short, meaningful title and a clear +description. Add as much relevant information as you can, and, if possible, a +test case. -## Want to work on an existing issue? +### Want to work on an existing issue? This is the best way how you can help us to make our documentation better! Take a look at issues tagged with @@ -59,64 +66,11 @@ non-community members who have already made contributions to the [OpenTelemetry organization][org]. After confirmation through a maintainer, plan to provide a PR shortly or let maintainers now if you run into any blockers. -## Sending Pull Requests - -Enhancements and fixes to the website are most welcome! - -Before sending a new [pull request][pr] (PR), take a look at existing -[pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) -and -[issues](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) -to see if the proposed change or fix has been discussed in the past, or if the -change was already implemented but not yet released. - -### Quick fixes - -For small changes to a single file, you can edit directly in GitHub by clicking -**Edit this file** button. After forking the repository, follow the instructions -in [Editing files][]. - -However, formatting may still be needed, like reducing line lengths in the -edited file. The options for fixing formatting are: - -- Checking out the project and running the CLI scripts mentioned in - [Submitting a change](#submitting-a-change). -- Commenting `/fix:format` on your pull request to trigger an automated script. - This requires a unique branch name, which can be edited under _View all - branches_ in your fork. - -For larger fixes, follow the -[instructions to setup a development environment](#development) below. - -### PR Guidelines - -Before a PR gets merged, it will sometimes require a few iterations of -review-and-edit. To help us and yourself make this process as easy as possible, -we ask that adhere to the following: - -- If your PR isn't a [quick fix](#quick-fixes), then **work from a fork**: Click - the [Fork](https://github.com/open-telemetry/opentelemetry.io/fork) button at - the top of the repository and clone the fork locally. When you are ready, - raise a PR with the upstream repository. -- **Do not work from the `main`** branch of your fork, but create a PR-specific - branch. -- Ensure that maintainers are - [allowed to apply changes to your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). +## Contributor's guide -### Merge requirements - -- No “changes requested” reviews by approvers, maintainers, technical committee - members, or subject matter experts -- No unresolved conversations -- Approved by at least one approver -- No failing PR checks -- PR branch is up-to-date with the base branch - -> **Important** -> -> Do not worry too much about failing PR checks! Community members will help you -> to get them fixed, by either providing you with instructions how to fix them -> or by fixing them on your behave. +To learn how to contribute fixes and new content to this project, read the +[Contributor's guide](/content/en/docs/contribute), which includes a style guide +and useful information on the review process. ## Development @@ -219,24 +173,6 @@ The website is built from the following content: [content-modules]: https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules -### Submitting a change - -Before submitting a change to the repository, run the following command and -address any reported issues. Also commit any files changed by the `fix` script: - -```sh -npm run test-and-fix -``` - -To separately test and fix issues with your files, run: - -```sh -npm run test # checks but does not update any files -npm run fix # may update files -``` - -To list available NPM scripts, run `npm run`. - ### Submodule changes If you change any content inside of a [content-modules][] submodule, then you'll @@ -255,17 +191,6 @@ submodule itself. > You'll also need to `git fetch --unshallow` the submodule before you can > submit a PR. Alternatively, set `DEPTH=100` and re-fetch submodules. -### Site deploys and PR previews - -If you submit a PR, Netlify will create a [deploy preview][] so that you can -review your changes. Once your PR is merged, Netlify deploys the updated site to -the production server. - -> **Note**: PR previews include _draft pages_, but production builds do not. - -To see deploy logs and more, visit project's [dashboard][] -- Netlify login -required. - ## Approver and Maintainer practices This last section includes guidelines and some common practices used by @@ -302,18 +227,12 @@ approvers and maintainers while doing code reviews: [.nvmrc]: .nvmrc [clone]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository -[dashboard]: https://app.netlify.com/sites/opentelemetry/overview -[deploy preview]: - https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/ -[editing files]: - https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files [fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo [gitpod.io]: https://gitpod.io [gitpod.io/workspaces]: https://gitpod.io/workspaces [hugo]: https://gohugo.io [localhost:1313]: http://localhost:1313 [localhost:8888]: http://localhost:8888 -[netlify]: https://netlify.com [new-issue]: https://github.com/open-telemetry/opentelemetry.io/issues/new/choose [nodejs-rel]: https://nodejs.org/en/about/previous-releases @@ -323,5 +242,3 @@ approvers and maintainers while doing code reviews: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating [nvm-windows]: https://github.com/coreybutler/nvm-windows [org]: https://github.com/open-telemetry -[pr]: - https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 6b1a67e38312..cd51b57ef6ab 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -148,6 +148,9 @@ If a reviewer asks you to make changes: When your review is complete, a reviewer merges your PR and your changes goes live a few minutes later. +{{% alert title="Tip" %}} Comment `/fix:format` on your pull request to trigger +an automated check for formatting issues. {{% /alert %}} + ### Work from a local fork {#fork-the-repo} If you're more experienced with Git, or if your changes are larger than a few @@ -297,23 +300,6 @@ When you are ready to submit a pull request, commit your changes. 1. Once the changes are pushed, GitHub lets you know that you can create a PR. -#### Preview your changes locally {#preview-locally} - -Preview your changes locally before pushing them or opening a pull request. A -preview lets you catch build errors or markdown formatting problems. - -To build and serve the site locally with Hugo, run the following command: - -```shell -npm run serve -``` - -Navigate to `https://localhost:1313` in your web browser to see the local -preview. Hugo watches the changes and rebuilds the site as needed. - -To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or -close the terminal window. - #### Open a pull request from your fork {#open-a-pr} Figure 3 shows the steps to open a PR from your fork to the @@ -387,6 +373,67 @@ Other checks might also fail, including: GitHub also automatically assigns labels to a PR to help reviewers. +#### Fix content issues automatically + +Before submitting a change to the repository, run the following command and +address any reported issues. Also commit any files changed by the `fix` script: + +```sh +npm run test-and-fix +``` + +To separately test and fix issues with your files, run: + +```sh +npm run test # checks but does not update any files +npm run fix # may update files +``` + +To list available NPM scripts, run `npm run`. + +#### Preview your changes locally {#preview-locally} + +Preview your changes locally before pushing them or opening a pull request. A +preview lets you catch build errors or markdown formatting problems. + +To build and serve the site locally with Hugo, run the following command: + +```shell +npm run serve +``` + +Navigate to `https://localhost:1313` in your web browser to see the local +preview. Hugo watches the changes and rebuilds the site as needed. + +To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or +close the terminal window. + +#### Site deploys and PR previews + +If you submit a PR, Netlify will create a [deploy preview][] so that you can +review your changes. Once your PR is merged, Netlify deploys the updated site to +the production server. + +> **Note**: PR previews include _draft pages_, but production builds do not. + +To see deploy logs and more, visit project's [dashboard][] -- Netlify login +required. + +#### PR guidelines + +Before a PR gets merged, it will sometimes require a few iterations of +review-and-edit. To help us and yourself make this process as easy as possible, +we ask that adhere to the following: + +- If your PR isn't a quick fix, then **work from a fork**: Click the + [Fork](https://github.com/open-telemetry/opentelemetry.io/fork) button at the + top of the repository and clone the fork locally. When you are ready, raise a + PR with the upstream repository. +- **Do not work from the `main`** branch of your fork, but create a PR-specific + branch. +- Ensure that maintainers are + [allowed to apply changes to your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). + #### Changes from reviewers Sometimes reviewers commit to your pull request. Before making any other @@ -472,6 +519,23 @@ create a merge conflict. You must resolve all merge conflicts in your PR. The pull request no longer shows any conflicts. +#### Merge requirements + +Pull requests are merged when they comply with the following criteria: + +- All reviews by approvers, maintainers, technical committee members, or subject + matter experts have the status "Approved" +- No unresolved conversations +- Approved by at least one approver +- No failing PR checks +- PR branch is up-to-date with the base branch + +> **Important** +> +> Do not worry too much about failing PR checks! Community members will help you +> to get them fixed, by either providing you with instructions how to fix them +> or by fixing them on your behave. + ## Open an issue If you want to suggest improvements to existing content or notice an error, open @@ -504,7 +568,7 @@ vulnerabilities. 1. Submit the issue. -## How to file great issues +### How to file great issues Keep the following in mind when filing an issue: @@ -548,3 +612,7 @@ the templates with as much detail as possible when you file issues or PRs. - Visit the [OpenTelemetry community site](/community/). - Add your application to the [Registry](/ecosystem). - Submit a [blog post or case study](/docs/contribute/blogs-case-studies/). + +[dashboard]: https://app.netlify.com/sites/opentelemetry/overview +[deploy preview]: + https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/ diff --git a/content/en/docs/contribute/blogs-case-studies.md b/content/en/docs/contribute/blogs-case-studies.md index 5f08e2456ac7..1ef62aabcda5 100644 --- a/content/en/docs/contribute/blogs-case-studies.md +++ b/content/en/docs/contribute/blogs-case-studies.md @@ -11,74 +11,98 @@ and any news that might be relevant to the OpenTelemetry community. This includes end users and developers. Anyone can write a blog post and submit it for review. -## Submit a post +## Before submitting a blog post Blog posts should not be commercial in nature and should consist of original -content that applies broadly to the OpenTelemetry community. Appropriate blog -content includes: +content that applies broadly to the OpenTelemetry community. + +Verify that your intended content broadly applies to the OpenTelemetry Community +. Appropriate content includes: - New OpenTelemetry capabilities - OpenTelemetry projects updates - Updates from Special Interest Groups - Tutorials and walkthroughs -- Thought leadership around OpenTelemetry -- OpenTelemetry Partner OSS integration +- OpenTelemetry Integrations Unsuitable content includes: - Vendor product pitches -- Partner updates without an integration and customer story -To submit a blog post, follow these steps: +To submit a blog post, +[raise an issue](https://github.com/open-telemetry/opentelemetry.io/issues/new?title=New%20Blog%20Post:%20%3Ctitle%3E) +with the title and a short description of your blog post. If you are not a +[Member](https://github.com/open-telemetry/community/blob/main/community-membership.md#member), +you also need to provide a _sponsor_ for your blog post, who is a Member (by +that definition) and who is willing to provide a first review of your blog post. + +If you do not raise an issue before providing your PR, we may request you to do +so before providing a review. + +## Submit a blog post + +You can submit a blog post either by forking this repository and writing it +locally or by using the GitHub UI. In both cases we ask you to follow the +instructions provided by the +[blog post template](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/blog.md). + +**Note**: Before writing a blog post, ask yourself if your content also might be +a good addition to the documentation. If the answer is "yes", create a new issue +or pull request (PR) with your content to get it added to the docs. + +### Fork and write locally + +After you've set up the local fork you can create a blog post using a template. +Follow these steps to create a post from the template: + +1. Run the following command from the repository root: + + ```sh + npx hugo new content/en/blog/2023/short-name-for-post.md + ``` + + If your post has images or other assets, run the following command: + + ```sh + npx hugo new content/en/blog/2023/short-name-for-post/index.md + ``` + +1. Edit the Markdown file at the path you provided in the previous command. The + file is initialized from the blog-post starter under + [archetypes](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/). -1. [Sign the CLA](https://docs.linuxfoundation.org/lfx/easycla/contributors) if - you have not yet done so. +1. Put assets, like images or other files, into the folder you've created. -1. Have a look at the Markdown format for existing blog posts in the - [opentelemetry.io repository](https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/blog). +1. When your post is ready, submit it through a pull request. -1. Write out your blog post in a text editor of your choice. +### Use the GitHub UI -1. On the same link from step 2, select **Create new file**. Paste your content - into the editor. Name the file to match the proposed title of the blog post, - but don’t put the date in the file name. The blog reviewers will work with - you on the final file name and the date the blog will be published. +If you prefer not to create a local fork, you can use the GitHub UI to create a +new post. Follow these steps to add a post using the UI: -1. When you save the file, GitHub will walk you through the pull request - process. +1. Go to the + [blog post template](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/blog.md) + and click on **Copy raw content** at the top right of the menu. -1. A blog post reviewer will review your submission and work with you on - feedback and final details. When the blog post is approved, the blog will be - scheduled for publication. +1. Select + [Create a new file](https://github.com/open-telemetry/opentelemetry.io/new/main). -## Guidelines and expectations +1. Paste the content from the template you copied in the first step. -- Blog posts should not be vendor pitches. +1. Name your file, for example + `content/en/blog/2022/short-name-for-your-blog-post/index.md`. - - Articles must contain content that applies broadly to the OpenTelemetry - community. For example, a submission should focus on upstream OpenTelemetry - as opposed to vendor-specific configurations. - - Links should primarily be to the official OpenTelemetry documentation. When - using external references, links should be diverse - For example a - submission shouldn't contain only links back to a single company's blog. +1. Edit the Markdown file in GitHub. -- Blog posts are not published on specific dates. +1. When your post is ready, select **Propose changes** and follow the + instructions. - - Articles are reviewed by community volunteers. We'll try our best to - accommodate specific timing, but we make no guarantees. - - Many core parts of the OpenTelemetry projects submit blog posts during - release windows, delaying publication times. Consider submitting during a - quieter period of the release cycle. - - If you are looking for greater coordination on post release dates, - coordinating with [CNCF marketing](https://www.cncf.io/about/contact/) is a - more appropriate choice than submitting a blog post. +## Publication timelines -- Blog posts should be relevant to OpenTelemetry users. +The OpenTelemetry blog doesn't follow a strict publication timeline, this means: - - Topics related to participation in or results of OpenTelemetry SIGs - activities are always on topic. - - Posts about other CNCF projects may or may not be on topic. We recommend - asking the blog team before submitting a draft. - - Many CNCF projects have their own blog. These are often a better choice for - posts. There are times of major feature or milestone for a CNCF project that - users would be interested in reading on the OpenTelemetry blog. +- Your blog post will be published when it has all the approvals required. +- Publication can be postponed if needed, but maintainers can't guarantee + publication at or before a certain date. +- Certain blog posts (major announcements) take precedence and may be published + before your blog post. diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contribute/style-guide.md index 6b7a9daadc5e..cd1f93f55d8b 100644 --- a/content/en/docs/contribute/style-guide.md +++ b/content/en/docs/contribute/style-guide.md @@ -2,7 +2,7 @@ title: Documentation style guide linkTitle: Style guide weight: 40 -slug: style-guide open-telemetry postgre textlintrc +cSpell:ignore: style-guide open-telemetry postgre textlintrc --- The OpenTelemetry documentation adheres to the diff --git a/static/refcache.json b/static/refcache.json index 5321c99c9588..6df7e60a6c8f 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -83,6 +83,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T13:39:44.708765-04:00" }, + "https://app.netlify.com/sites/opentelemetry/overview": { + "StatusCode": 206, + "LastSeen": "2023-12-13T15:27:13.292839+01:00" + }, "https://app.telemetryhub.com/docs": { "StatusCode": 200, "LastSeen": "2023-06-29T12:27:18.815688-04:00" @@ -979,6 +983,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T15:46:50.059623-04:00" }, + "https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork": { + "StatusCode": 206, + "LastSeen": "2023-12-13T15:27:14.272624+01:00" + }, "https://docs.google.com/document/d/15vR7D1x2tKd7u3zaTF0yH1WaHkUr2T4hhr7OyiZgmBg/edit#heading=h.4xuru5ljcups": { "StatusCode": 200, "LastSeen": "2023-06-29T15:52:33.514228-04:00" @@ -3679,6 +3687,10 @@ "StatusCode": 200, "LastSeen": "2023-12-12T09:05:06.564186+01:00" }, + "https://github.com/open-telemetry/opentelemetry.io/fork": { + "StatusCode": 200, + "LastSeen": "2023-12-13T15:27:13.947245+01:00" + }, "https://github.com/open-telemetry/opentelemetry.io/issues/new": { "StatusCode": 200, "LastSeen": "2023-06-30T08:31:06.342368-04:00" @@ -6411,6 +6423,10 @@ "StatusCode": 206, "LastSeen": "2023-12-12T09:05:07.468279+01:00" }, + "https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/": { + "StatusCode": 206, + "LastSeen": "2023-12-13T15:27:12.735575+01:00" + }, "https://www.nomadproject.io": { "StatusCode": 206, "LastSeen": "2023-06-30T08:50:51.721695-04:00" From 6478ee2b156a61af7d4fc9fcc490e6dcd6b1a86d Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 16:06:36 +0100 Subject: [PATCH 21/62] Edit --- content/en/docs/contribute/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contribute/style-guide.md index cd1f93f55d8b..7cd932e06a4e 100644 --- a/content/en/docs/contribute/style-guide.md +++ b/content/en/docs/contribute/style-guide.md @@ -2,7 +2,7 @@ title: Documentation style guide linkTitle: Style guide weight: 40 -cSpell:ignore: style-guide open-telemetry postgre textlintrc +cSpell:ignore: open-telemetry postgre style-guide textlintrc --- The OpenTelemetry documentation adheres to the From 747515d7d4e8f8fd62ccb91fcd7f722a957933ff Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 14 Dec 2023 09:31:36 +0100 Subject: [PATCH 22/62] Update content/en/docs/contribute/_index.md Co-authored-by: Severin Neumann --- content/en/docs/contribute/_index.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index cd51b57ef6ab..4b4157dbc75e 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -148,8 +148,12 @@ If a reviewer asks you to make changes: When your review is complete, a reviewer merges your PR and your changes goes live a few minutes later. -{{% alert title="Tip" %}} Comment `/fix:format` on your pull request to trigger -an automated check for formatting issues. {{% /alert %}} +{{% alert title="Tip" %}} + +Comment `/fix:format` on your pull request to trigger +an automated check for formatting issues. + +{{% /alert %}} ### Work from a local fork {#fork-the-repo} From e23192bdfccd23c5953cd4b9db1fef4c352efd48 Mon Sep 17 00:00:00 2001 From: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Date: Thu, 14 Dec 2023 08:35:52 +0000 Subject: [PATCH 23/62] Results from /fix:format --- content/en/docs/contribute/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 4b4157dbc75e..e068431fa708 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -148,10 +148,10 @@ If a reviewer asks you to make changes: When your review is complete, a reviewer merges your PR and your changes goes live a few minutes later. -{{% alert title="Tip" %}} +{{% alert title="Tip" %}} -Comment `/fix:format` on your pull request to trigger -an automated check for formatting issues. +Comment `/fix:format` on your pull request to trigger an automated check for +formatting issues. {{% /alert %}} From 126fc4f57cbf20c63d2259c60d356df8c86562b1 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 11:06:01 +0100 Subject: [PATCH 24/62] Create folder and index --- content/en/docs/Contribute/_index.md | 6 ++++++ .../_index.md => Contribute/acknowledgements.md} | 0 2 files changed, 6 insertions(+) create mode 100644 content/en/docs/Contribute/_index.md rename content/en/docs/{acknowledgements/_index.md => Contribute/acknowledgements.md} (100%) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md new file mode 100644 index 000000000000..18552a4f8393 --- /dev/null +++ b/content/en/docs/Contribute/_index.md @@ -0,0 +1,6 @@ +--- +title: Contribute +description: Learn how to contribute to OpenTelemetry documentation. +weight: 200 +cSpell:ignore: +--- \ No newline at end of file diff --git a/content/en/docs/acknowledgements/_index.md b/content/en/docs/Contribute/acknowledgements.md similarity index 100% rename from content/en/docs/acknowledgements/_index.md rename to content/en/docs/Contribute/acknowledgements.md From 4e3bc131adacc24b6b94a33e1b5466303165aa8b Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 12:08:15 +0100 Subject: [PATCH 25/62] Initial structure and index --- content/en/docs/Contribute/_index.md | 46 +- .../new-content/blogs-case-studies.md | 199 +++++ .../Contribute/new-content/new-features.md | 143 ++++ .../docs/Contribute/new-content/open-a-pr.md | 628 ++++++++++++++ .../Contribute/roles-and-responsibilities.md | 237 ++++++ 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 +++++ .../en/docs/Contribute/style/style-guide.md | 674 +++++++++++++++ .../docs/Contribute/style/write-new-topic.md | 170 ++++ .../Contribute/suggesting-improvements.md | 67 ++ 17 files changed, 3835 insertions(+), 3 deletions(-) create mode 100644 content/en/docs/Contribute/new-content/blogs-case-studies.md create mode 100644 content/en/docs/Contribute/new-content/new-features.md create mode 100644 content/en/docs/Contribute/new-content/open-a-pr.md create mode 100644 content/en/docs/Contribute/roles-and-responsibilities.md create mode 100644 content/en/docs/Contribute/style/_index.md create mode 100644 content/en/docs/Contribute/style/content-guide.md create mode 100644 content/en/docs/Contribute/style/content-organization.md create mode 100644 content/en/docs/Contribute/style/diagram-guide.md create mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/example1.md create mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/example2.md create mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/index.md create mode 100644 content/en/docs/Contribute/style/hugo-shortcodes/podtemplate.json create mode 100644 content/en/docs/Contribute/style/page-content-types.md create mode 100644 content/en/docs/Contribute/style/style-guide.md create mode 100644 content/en/docs/Contribute/style/write-new-topic.md create mode 100644 content/en/docs/Contribute/suggesting-improvements.md diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 18552a4f8393..851cc0199d80 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -1,6 +1,46 @@ --- title: Contribute -description: Learn how to contribute to OpenTelemetry documentation. +description: Learn how to contribute to the OpenTelemetry documentation. weight: 200 -cSpell:ignore: ---- \ No newline at end of file +cSpell:ignore: +--- + +This website is maintained by +[OpenTelemetry SIG Comms](/docs/contribute/#get-involved-with-sig-comms). + +OpenTelemetry documentation contributors: + +- Improve existing content. +- Create new content. +- Update the OpenTelemetry Registry. +- Improve the code that builds the site. + +See also the general +[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) +, which provides details on the Contributor License Agreement and the Code of +Conduct. + +## Get started + +You can open an issue about OpenTelemetry documentation, or contribute a change +with a pull request (PR) to the +[`open-telemetry/opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). + +To contribute, you need to be familiar with the following techs and tools: + +* [git](https://git-scm.com/) +* [GitHub](https://lab.github.com/) +* Markdown +* YAML + +For technical details concerning how the documentation is built and tested +locally, see the +[CONTRIBUTING.md](https://github.com/open-telemetry/opentelemetry.io/blob/main/CONTRIBUTING.md) +file. + +## Other ways to contribute + +- Visit the [OpenTelemetry community site](/community/). +- Add your application to the [Registry](/ecosystem). +- Submit a [blog post or case study](/docs/contribute/new-content/blogs-case-studies/). + diff --git a/content/en/docs/Contribute/new-content/blogs-case-studies.md b/content/en/docs/Contribute/new-content/blogs-case-studies.md new file mode 100644 index 000000000000..72d234e7a84b --- /dev/null +++ b/content/en/docs/Contribute/new-content/blogs-case-studies.md @@ -0,0 +1,199 @@ +--- +title: Submitting blog posts and case studies +linktitle: Blogs and case studies +slug: blogs-case-studies +content_type: concept +weight: 30 +--- + + + + +Anyone can write a blog post and submit it for review. +Case studies require extensive review before they're approved. + + + +## The Kubernetes Blog + +The Kubernetes blog is used by the project to communicate new features, community reports, and any +news that might be relevant to the Kubernetes community. This includes end users and developers. +Most of the blog's content is about things happening in the core project, but we encourage you to +submit about things happening elsewhere in the ecosystem too! + +Anyone can write a blog post and submit it for review. + +### Submit a Post + +Blog posts should not be commercial in nature and should consist of original content that applies +broadly to the Kubernetes community. Appropriate blog content includes: + +- New Kubernetes capabilities +- Kubernetes projects updates +- Updates from Special Interest Groups +- Tutorials and walkthroughs +- Thought leadership around Kubernetes +- Kubernetes Partner OSS integration +- **Original content only** + +Unsuitable content includes: + +- Vendor product pitches +- Partner updates without an integration and customer story +- Syndicated posts (language translations ok) + +To submit a blog post, follow these steps: + +1. [Sign the CLA](https://github.com/kubernetes/community/blob/master/CLA.md) + if you have not yet done so. + +1. Have a look at the Markdown format for existing blog posts in the + [website repository](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts). + +1. Write out your blog post in a text editor of your choice. + +1. On the same link from step 2, click the Create new file button. Paste your content into the editor. + Name the file to match the proposed title of the blog post, but don’t put the date in the file name. + The blog reviewers will work with you on the final file name and the date the blog will be published. + +1. When you save the file, GitHub will walk you through the pull request process. + +1. A blog post reviewer will review your submission and work with you on feedback and final details. + When the blog post is approved, the blog will be scheduled for publication. + +### Guidelines and expectations + +- Blog posts should not be vendor pitches. + + - Articles must contain content that applies broadly to the Kubernetes community. For example, a + submission should focus on upstream Kubernetes as opposed to vendor-specific configurations. + Check the [Documentation style guide](/docs/contribute/style/content-guide/#what-s-allowed) for + what is typically allowed on Kubernetes properties. + - Links should primarily be to the official Kubernetes documentation. When using external + references, links should be diverse - For example a submission shouldn't contain only links + back to a single company's blog. + - Sometimes this is a delicate balance. The [blog team](https://kubernetes.slack.com/messages/sig-docs-blog/) + is there to give guidance on whether a post is appropriate for the Kubernetes blog, so don't + hesitate to reach out. + +- Blog posts are not published on specific dates. + + - Articles are reviewed by community volunteers. We'll try our best to accommodate specific + timing, but we make no guarantees. + - Many core parts of the Kubernetes projects submit blog posts during release windows, delaying + publication times. Consider submitting during a quieter period of the release cycle. + - If you are looking for greater coordination on post release dates, coordinating with + [CNCF marketing](https://www.cncf.io/about/contact/) is a more appropriate choice than submitting a blog post. + - Sometimes reviews can get backed up. If you feel your review isn't getting the attention it needs, + you can reach out to the blog team on the [`#sig-docs-blog` Slack channel](https://kubernetes.slack.com/messages/sig-docs-blog/) + to ask in real time. + +- Blog posts should be relevant to Kubernetes users. + + - Topics related to participation in or results of Kubernetes SIGs activities are always on + topic (see the work in the [Contributor Comms Team](https://github.com/kubernetes/community/blob/master/communication/contributor-comms/blogging-resources/blog-guidelines.md#contributor-comms-blog-guidelines) + for support on these posts). + - The components of Kubernetes are purposely modular, so tools that use existing integration + points like CNI and CSI are on topic. + - Posts about other CNCF projects may or may not be on topic. We recommend asking the blog team + before submitting a draft. + - Many CNCF projects have their own blog. These are often a better choice for posts. There are + times of major feature or milestone for a CNCF project that users would be interested in + reading on the Kubernetes blog. + - Blog posts about contributing to the Kubernetes project should be in the + [Kubernetes Contributors site](https://kubernetes.dev) + +- Blog posts should be original content + + - The official blog is not for repurposing existing content from a third party as new content. + - The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows + commercial use of the content for commercial purposes, but not the other way around. + +- Blog posts should aim to be future proof + + - Given the development velocity of the project, we want evergreen content that won't require + updates to stay accurate for the reader. + - It can be a better choice to add a tutorial or update official documentation than to write a + high level overview as a blog post. + - Consider concentrating the long technical content as a call to action of the blog post, and + focus on the problem space or why readers should care. + +### Technical Considerations for submitting a blog post + +Submissions need to be in Markdown format to be used by the [Hugo](https://gohugo.io/) generator +for the blog. There are [many resources available](https://gohugo.io/documentation/) on how to use +this technology stack. + +We recognize that this requirement makes the process more difficult for less-familiar folks to +submit, and we're constantly looking at solutions to lower this bar. If you have ideas on how to +lower the barrier, please volunteer to help out. + +The SIG Docs [blog subproject](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject) +manages the review process for blog posts. For more information, see +[Submit a post](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject#submit-a-post). + +To submit a blog post follow these directions: + +- [Open a pull request](/docs/contribute/new-content/open-a-pr/#fork-the-repo) with a new blog post. + New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/main/content/en/blog/_posts) + directory. + +- Ensure that your blog post follows the correct naming conventions and the following frontmatter + (metadata) information: + + - The Markdown file name must follow the format `YYYY-MM-DD-Your-Title-Here.md`. For example, + `2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md`. + - Do **not** include dots in the filename. A name like `2020-01-01-whats-new-in-1.19.md` causes + failures during a build. + - The front matter must include the following: + + ```yaml + --- + layout: blog + title: "Your Title Here" + date: YYYY-MM-DD + slug: text-for-URL-link-here-no-spaces + --- + ``` + + - The first or initial commit message should be a short summary of the work being done and + should stand alone as a description of the blog post. Please note that subsequent edits to + your blog will be squashed into this main commit, so it should be as useful as possible. + + - Examples of a good commit message: + - _Add blog post on the foo kubernetes feature_ + - _blog: foobar announcement_ + - Examples of bad commit message: + - _Add blog post_ + - _._ + - _initial commit_ + - _draft post_ + + - The blog team will then review your PR and give you comments on things you might need to fix. + After that the bot will merge your PR and your blog post will be published. + + - If the content of the blog post contains only content that is not expected to require updates + to stay accurate for the reader, it can be marked as evergreen and exempted from the automatic + warning about outdated content added to blog posts older than one year. + + - To mark a blog post as evergreen, add this to the front matter: + + ```yaml + evergreen: true + ``` + - Examples of content that should not be marked evergreen: + - **Tutorials** that only apply to specific releases or versions and not all future versions + - References to pre-GA APIs or features + +## Submit a case study + +Case studies highlight how organizations are using Kubernetes to solve real-world problems. The +Kubernetes marketing team and members of the {{< glossary_tooltip text="CNCF" term_id="cncf" >}} +collaborate with you on all case studies. + +Have a look at the source for the +[existing case studies](https://github.com/kubernetes/website/tree/main/content/en/case-studies). + +Refer to the [case study guidelines](https://github.com/cncf/foundation/blob/master/case-study-guidelines.md) +and submit your request as outlined in the guidelines. + diff --git a/content/en/docs/Contribute/new-content/new-features.md b/content/en/docs/Contribute/new-content/new-features.md new file mode 100644 index 000000000000..3b71e2d5316d --- /dev/null +++ b/content/en/docs/Contribute/new-content/new-features.md @@ -0,0 +1,143 @@ +--- +title: Documenting a feature for a release +linktitle: Documenting for a release +content_type: concept +main_menu: true +weight: 20 +card: + name: contribute + weight: 45 + title: Documenting a feature for a release +--- + + +Each major Kubernetes release introduces new features that require documentation. New releases also bring updates to existing features and documentation (such as upgrading a feature from alpha to beta). + +Generally, the SIG responsible for a feature submits draft documentation of the +feature as a pull request to the appropriate development branch of the +`kubernetes/website` repository, and someone on the SIG Docs team provides +editorial feedback or edits the draft directly. This section covers the branching +conventions and process used during a release by both groups. + + + + + +## For documentation contributors + +In general, documentation contributors don't write content from scratch for a release. +Instead, they work with the SIG creating a new feature to refine the draft documentation and make it release ready. + +After you've chosen a feature to document or assist, ask about it in the `#sig-docs` +Slack channel, in a weekly SIG Docs meeting, or directly on the PR filed by the +feature SIG. If you're given the go-ahead, you can edit into the PR using one of +the techniques described in +[Commit into another person's PR](/docs/contribute/review/for-approvers/#commit-into-another-person-s-pr). + +### Find out about upcoming features + +To find out about upcoming features, attend the weekly SIG Release meeting (see +the [community](/community/) page for upcoming meetings) +and monitor the release-specific documentation +in the [kubernetes/sig-release](https://github.com/kubernetes/sig-release/) +repository. Each release has a sub-directory in the [/sig-release/tree/master/releases/](https://github.com/kubernetes/sig-release/tree/master/releases) +directory. The sub-directory contains a release schedule, a draft of the release +notes, and a document listing each person on the release team. + +The release schedule contains links to all other documents, meetings, +meeting minutes, and milestones relating to the release. It also contains +information about the goals and timeline of the release, and any special +processes in place for this release. Near the bottom of the document, several +release-related terms are defined. + +This document also contains a link to the **Feature tracking sheet**, which is +the official way to find out about all new features scheduled to go into the +release. + +The release team document lists who is responsible for each release role. If +it's not clear who to talk to about a specific feature or question you have, +either attend the release meeting to ask your question, or contact the release +lead so that they can redirect you. + +The release notes draft is a good place to find out about +specific features, changes, deprecations, and more about the release. The +content is not finalized until late in the release cycle, so use caution. + +### Feature tracking sheet + +The feature tracking sheet [for a given Kubernetes release](https://github.com/kubernetes/sig-release/tree/master/releases) +lists each feature that is planned for a release. +Each line item includes the name of the feature, a link to the feature's main +GitHub issue, its stability level (Alpha, Beta, or Stable), the SIG and +individual responsible for implementing it, whether it +needs docs, a draft release note for the feature, and whether it has been +merged. Keep the following in mind: + +- Beta and Stable features are generally a higher documentation priority than + Alpha features. +- It's hard to test (and therefore to document) a feature that hasn't been merged, + or is at least considered feature-complete in its PR. +- Determining whether a feature needs documentation is a manual process. Even if + a feature is not marked as needing docs, you may need to document the feature. + +## For developers or other SIG members + +This section is information for members of other Kubernetes SIGs documenting new features +for a release. + +If you are a member of a SIG developing a new feature for Kubernetes, you need +to work with SIG Docs to be sure your feature is documented in time for the +release. Check the +[feature tracking spreadsheet](https://github.com/kubernetes/sig-release/tree/master/releases) +or check in the `#sig-release` Kubernetes Slack channel to verify scheduling details and +deadlines. + +### Open a placeholder PR + +1. Open a **draft** pull request against the +`dev-{{< skew nextMinorVersion >}}` branch in the `kubernetes/website` repository, with a small +commit that you will amend later. To create a draft pull request, use the +Create Pull Request drop-down and select **Create Draft Pull Request**, +then click **Draft Pull Request**. +2. Edit the pull request description to include links to [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) +PR(s) and [kubernetes/enhancements](https://github.com/kubernetes/enhancements) issue(s). +3. Leave a comment on the related [kubernetes/enhancements](https://github.com/kubernetes/enhancements) +issue with a link to the PR to notify the docs person managing this release that +the feature docs are coming and should be tracked for the release. + +If your feature does not need +any documentation changes, make sure the sig-release team knows this, by +mentioning it in the `#sig-release` Slack channel. If the feature does need +documentation but the PR is not created, the feature may be removed from the +milestone. + +### PR ready for review + +When ready, populate your placeholder PR with feature documentation and change +the state of the PR from draft to **ready for review**. To mark a pull request +as ready for review, navigate to the merge box and click **Ready for review**. + +Do your best to describe your feature and how to use it. If you need help structuring your documentation, ask in the `#sig-docs` Slack channel. + +When you complete your content, the documentation person assigned to your feature reviews it. +To ensure technical accuracy, the content may also require a technical review from corresponding SIG(s). +Use their suggestions to get the content to a release ready state. + +If your feature is an Alpha or Beta feature and is behind a feature gate, +make sure you add it to [Alpha/Beta Feature gates](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features) +table as part of your pull request. With new feature gates, a description of +the feature gate is also required. If your feature is GA'ed or deprecated, +make sure to move it from the +[Feature gates for Alpha/Feature](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features) table +to [Feature gates for graduated or deprecated features](/docs/reference/command-line-tools-reference/feature-gates-removed/#feature-gates-that-are-removed) +table with Alpha and Beta history intact. + +If your feature needs documentation and the first draft +content is not received, the feature may be removed from the milestone. + +### All PRs reviewed and ready to merge + +If your PR has not yet been merged into the `dev-{{< skew nextMinorVersion >}}` branch by the release deadline, work with the +docs person managing the release to get it in by the deadline. If your feature needs +documentation and the docs are not ready, the feature may be removed from the +milestone. \ No newline at end of file diff --git a/content/en/docs/Contribute/new-content/open-a-pr.md b/content/en/docs/Contribute/new-content/open-a-pr.md new file mode 100644 index 000000000000..382befe11694 --- /dev/null +++ b/content/en/docs/Contribute/new-content/open-a-pr.md @@ -0,0 +1,628 @@ +--- +title: Opening a pull request +content_type: concept +weight: 10 +card: + name: contribute + weight: 40 +--- + + + +{{< note >}} +**Code developers**: If you are documenting a new feature for an +upcoming Kubernetes release, see +[Document a new feature](/docs/contribute/new-content/new-features/). +{{< /note >}} + +To contribute new content pages or improve existing content pages, open a pull request (PR). +Make sure you follow all the requirements in the +[Before you begin](/docs/contribute/new-content/) section. + +If your change is small, or you're unfamiliar with git, read +[Changes using GitHub](#changes-using-github) to learn how to edit a page. + +If your changes are large, read [Work from a local fork](#fork-the-repo) to learn how to make +changes locally on your computer. + + + +## Changes using GitHub + +If you're less experienced with git workflows, here's an easier method of +opening a pull request. Figure 1 outlines the steps and the details follow. + + + + +{{< mermaid >}} +flowchart LR +A([fa:fa-user New
Contributor]) --- id1[(kubernetes/website
GitHub)] +subgraph tasks[Changes using GitHub] +direction TB + 0[ ] -.- + 1[1. Edit this page] --> 2[2. Use GitHub markdown
editor to make changes] + 2 --> 3[3. fill in Propose file change] + +end +subgraph tasks2[ ] +direction TB +4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] +6 --> 7[7. select Create pull request] +end + +id1 --> tasks --> tasks2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,1,2,3,4,5,6,7 grey +class 0 spacewhite +class tasks,tasks2 white +class id1 k8s +{{}} + +Figure 1. Steps for opening a PR using GitHub. + +1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. + +1. Make your changes in the GitHub markdown editor. + +1. Below the editor, fill in the **Propose file change** form. + In the first field, give your commit message a title. + In the second field, provide a description. + + {{< note >}} + Do not use any [GitHub Keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) + in your commit message. You can add those to the pull request description later. + {{< /note >}} + +1. Select **Propose file change**. + +1. Select **Create pull request**. + +1. The **Open a pull request** screen appears. Fill in the form: + + - The **Subject** field of the pull request defaults to the commit summary. + You can change it if needed. + - The **Body** contains your extended commit message, if you have one, + and some template text. Add the + details the template text asks for, then delete the extra template text. + - Leave the **Allow edits from maintainers** checkbox selected. + + {{< note >}} + PR descriptions are a great way to help reviewers understand your change. + For more information, see [Opening a PR](#open-a-pr). + {{}} + +1. Select **Create pull request**. + +### Addressing feedback in GitHub + +Before merging a pull request, Kubernetes community members review and +approve it. The `k8s-ci-robot` suggests reviewers based on the nearest +owner mentioned in the pages. If you have someone specific in mind, +leave a comment with their GitHub username in it. + +If a reviewer asks you to make changes: + +1. Go to the **Files changed** tab. +1. Select the pencil (edit) icon on any files changed by the pull request. +1. Make the changes requested. +1. Commit the changes. + +If you are waiting on a reviewer, reach out once every 7 days. You can also post a message in the +`#sig-docs` Slack channel. + +When your review is complete, a reviewer merges your PR and your changes go live a few minutes later. + +## Work from a local fork {#fork-the-repo} + +If you're more experienced with git, or if your changes are larger than a few lines, +work from a local fork. + +Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed +on your computer. You can also use a git UI application. + +Figure 2 shows the steps to follow when you work from a local fork. The details for each step follow. + + + + +{{< mermaid >}} +flowchart LR +1[Fork the kubernetes/website
repository] --> 2[Create local clone
and set upstream] +subgraph changes[Your changes] +direction TB +S[ ] -.- +3[Create a branch
example: my_new_branch] --> 3a[Make changes using
text editor] --> 4["Preview your changes
locally using Hugo
(localhost:1313)
or build container image"] +end +subgraph changes2[Commit / Push] +direction TB +T[ ] -.- +5[Commit your changes] --> 6[Push commit to
origin/my_new_branch] +end + +2 --> changes --> changes2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class 1,2,3,3a,4,5,6 grey +class S,T spacewhite +class changes,changes2 white +{{}} + +Figure 2. Working from a local fork to make your changes. + +### Fork the kubernetes/website repository + +1. Navigate to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository. +1. Select **Fork**. + +### Create a local clone and set the upstream + +1. In a terminal window, clone your fork and update the [Docsy Hugo theme](https://github.com/google/docsy#readme): + + ```shell + git clone git@github.com:/website + cd website + git submodule update --init --recursive --depth 1 + ``` + +1. Navigate to the new `website` directory. Set the `kubernetes/website` repository as the `upstream` remote: + + ```shell + cd website + + git remote add upstream https://github.com/kubernetes/website.git + ``` + +1. Confirm your `origin` and `upstream` repositories: + + ```shell + git remote -v + ``` + + Output is similar to: + + ```none + origin git@github.com:/website.git (fetch) + origin git@github.com:/website.git (push) + upstream https://github.com/kubernetes/website.git (fetch) + upstream https://github.com/kubernetes/website.git (push) + ``` + +1. Fetch commits from your fork's `origin/main` and `kubernetes/website`'s `upstream/main`: + + ```shell + git fetch origin + git fetch upstream + ``` + + This makes sure your local repository is up to date before you start making changes. + + {{< note >}} + This workflow is different than the + [Kubernetes Community GitHub Workflow](https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md). + You do not need to merge your local copy of `main` with `upstream/main` before pushing updates + to your fork. + {{< /note >}} + +### Create a branch + +1. Decide which branch base to your work on: + + - For improvements to existing content, use `upstream/main`. + - For new content about existing features, use `upstream/main`. + - For localized content, use the localization's conventions. For more information, see + [localizing Kubernetes documentation](/docs/contribute/localization/). + - For new features in an upcoming Kubernetes release, use the feature branch. For more + information, see [documenting for a release](/docs/contribute/new-content/new-features/). + - For long-running efforts that multiple SIG Docs contributors collaborate on, + like content reorganization, use a specific feature branch created for that effort. + + If you need help choosing a branch, ask in the `#sig-docs` Slack channel. + +1. Create a new branch based on the branch identified in step 1. This example assumes the base + branch is `upstream/main`: + + ```shell + git checkout -b upstream/main + ``` + +1. Make your changes using a text editor. + +At any time, use the `git status` command to see what files you've changed. + +### Commit your changes + +When you are ready to submit a pull request, commit your changes. + +1. In your local repository, check which files you need to commit: + + ```shell + git status + ``` + + Output is similar to: + + ```none + On branch + Your branch is up to date with 'origin/'. + + Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: content/en/docs/contribute/new-content/contributing-content.md + + no changes added to commit (use "git add" and/or "git commit -a") + ``` + +1. Add the files listed under **Changes not staged for commit** to the commit: + + ```shell + git add + ``` + + Repeat this for each file. + +1. After adding all the files, create a commit: + + ```shell + git commit -m "Your commit message" + ``` + + {{< note >}} + Do not use any [GitHub Keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) + in your commit message. You can add those to the pull request + description later. + {{< /note >}} + +1. Push your local branch and its new commit to your remote fork: + + ```shell + git push origin + ``` + +### Preview your changes locally {#preview-locally} + +It's a good idea to preview your changes locally before pushing them or opening a pull request. +A preview lets you catch build errors or markdown formatting problems. + +You can either build the website's container image or run Hugo locally. Building the container +image is slower but displays [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/), which can +be useful for debugging. + +{{< tabs name="tab_with_hugo" >}} +{{% tab name="Hugo in a container" %}} + +{{< note >}} +The commands below use Docker as default container engine. Set the `CONTAINER_ENGINE` environment +variable to override this behaviour. +{{< /note >}} + +1. Build the container image locally + _You only need this step if you are testing a change to the Hugo tool itself_ + + ```shell + # Run this in a terminal (if required) + make container-image + ``` + +1. Start Hugo in a container: + + ```shell + # Run this in a terminal + make container-serve + ``` + +1. In a web browser, navigate to `https://localhost:1313`. Hugo watches the + changes and rebuilds the site as needed. + +1. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, + or close the terminal window. + +{{% /tab %}} +{{% tab name="Hugo on the command line" %}} + +Alternately, install and use the `hugo` command on your computer: + +1. Install the [Hugo](https://gohugo.io/getting-started/installing/) version specified in + [`website/netlify.toml`](https://raw.githubusercontent.com/kubernetes/website/main/netlify.toml). + +1. If you have not updated your website repository, the `website/themes/docsy` directory is empty. + The site cannot build without a local copy of the theme. To update the website theme, run: + + ```shell + git submodule update --init --recursive --depth 1 + ``` + +1. In a terminal, go to your Kubernetes website repository and start the Hugo server: + + ```shell + cd /website + hugo server --buildFuture + ``` + +1. In a web browser, navigate to `https://localhost:1313`. Hugo watches the + changes and rebuilds the site as needed. + +1. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, + or close the terminal window. + +{{% /tab %}} +{{< /tabs >}} + +### Open a pull request from your fork to kubernetes/website {#open-a-pr} + +Figure 3 shows the steps to open a PR from your fork to the [kubernetes/website](https://github.com/kubernetes/website). The details follow. + +Please, note that contributors can mention `kubernetes/website` as `k/website`. + + + + +{{< mermaid >}} +flowchart LR +subgraph first[ ] +direction TB +1[1. Go to kubernetes/website repository] --> 2[2. Select New Pull Request] +2 --> 3[3. Select compare across forks] +3 --> 4[4. Select your fork from
head repository drop-down menu] +end +subgraph second [ ] +direction TB +5[5. Select your branch from
the compare drop-down menu] --> 6[6. Select Create Pull Request] +6 --> 7[7. Add a description
to your PR] +7 --> 8[8. Select Create pull request] +end + +first --> second + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +class 1,2,3,4,5,6,7,8 grey +class first,second white +{{}} + +Figure 3. Steps to open a PR from your fork to the [kubernetes/website](https://github.com/kubernetes/website). + +1. In a web browser, go to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository. +1. Select **New Pull Request**. +1. Select **compare across forks**. +1. From the **head repository** drop-down menu, select your fork. +1. From the **compare** drop-down menu, select your branch. +1. Select **Create Pull Request**. +1. Add a description for your pull request: + + - **Title** (50 characters or less): Summarize the intent of the change. + - **Description**: Describe the change in more detail. + + - If there is a related GitHub issue, include `Fixes #12345` or `Closes #12345` in the + description. GitHub's automation closes the mentioned issue after merging the PR if used. + If there are other related PRs, link those as well. + - If you want advice on something specific, include any questions you'd like reviewers to + think about in your description. + +1. Select the **Create pull request** button. + +Congratulations! Your pull request is available in [Pull requests](https://github.com/kubernetes/website/pulls). + +After opening a PR, GitHub runs automated tests and tries to deploy a preview using +[Netlify](https://www.netlify.com/). + +- If the Netlify build fails, select **Details** for more information. +- If the Netlify build succeeds, select **Details** opens a staged version of the Kubernetes + website with your changes applied. This is how reviewers check your changes. + +GitHub also automatically assigns labels to a PR, to help reviewers. You can add them too, if +needed. For more information, see [Adding and removing issue labels](/docs/contribute/review/for-approvers/#adding-and-removing-issue-labels). + +### Addressing feedback locally + +1. After making your changes, amend your previous commit: + + ```shell + git commit -a --amend + ``` + + - `-a`: commits all changes + - `--amend`: amends the previous commit, rather than creating a new one + +1. Update your commit message if needed. + +1. Use `git push origin ` to push your changes and re-run the Netlify tests. + + {{< note >}} + If you use `git commit -m` instead of amending, you must [squash your commits](#squashing-commits) + before merging. + {{< /note >}} + +#### Changes from reviewers + +Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits. + +1. Fetch commits from your remote fork and rebase your working branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + +1. After rebasing, force-push new changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +#### Merge conflicts and rebasing + +{{< note >}} +For more information, see [Git Branching - Basic Branching and Merging](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts), +[Advanced Merging](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging), or ask in the +`#sig-docs` Slack channel for help. +{{< /note >}} + +If another contributor commits changes to the same file in another PR, it can create a merge +conflict. You must resolve all merge conflicts in your PR. + +1. Update your fork and rebase your local branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + + Then force-push the changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +1. Fetch changes from `kubernetes/website`'s `upstream/main` and rebase your branch: + + ```shell + git fetch upstream + git rebase upstream/main + ``` + +1. Inspect the results of the rebase: + + ```shell + git status + ``` + + This results in a number of files marked as conflicted. + +1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. + Resolve the conflict and delete the conflict marker. + + {{< note >}} + For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). + {{< /note >}} + +1. Add the files to the changeset: + + ```shell + git add + ``` + +1. Continue the rebase: + + ```shell + git rebase --continue + ``` + +1. Repeat steps 2 to 5 as needed. + + After applying all commits, the `git status` command shows that the rebase is complete. + +1. Force-push the branch to your fork: + + ```shell + git push --force-with-lease origin + ``` + + The pull request no longer shows any conflicts. + +### Squashing commits + +{{< note >}} +For more information, see [Git Tools - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History), +or ask in the `#sig-docs` Slack channel for help. +{{< /note >}} + +If your PR has multiple commits, you must squash them into a single commit before merging your PR. +You can check the number of commits on your PR's **Commits** tab or by running the `git log` +command locally. + +{{< note >}} +This topic assumes `vim` as the command line text editor. +{{< /note >}} + +1. Start an interactive rebase: + + ```shell + git rebase -i HEAD~ + ``` + + Squashing commits is a form of rebasing. The `-i` switch tells git you want to rebase interactively. + `HEAD~}} + For more information, see [Interactive Mode](https://git-scm.com/docs/git-rebase#_interactive_mode). + {{< /note >}} + +1. Start editing the file. + + Change the original text: + + ```none + pick d875112ca Original commit + pick 4fa167b80 Address feedback 1 + pick 7d54e15ee Address feedback 2 + ``` + + To: + + ```none + pick d875112ca Original commit + squash 4fa167b80 Address feedback 1 + squash 7d54e15ee Address feedback 2 + ``` + + This squashes commits `4fa167b80 Address feedback 1` and `7d54e15ee Address feedback 2` into + `d875112ca Original commit`, leaving only `d875112ca Original commit` as a part of the timeline. + +1. Save and exit your file. + +1. Push your squashed commit: + + ```shell + git push --force-with-lease origin + ``` + +## Contribute to other repos + +The [Kubernetes project](https://github.com/kubernetes) contains 50+ repositories. Many of these +repositories contain documentation: user-facing help text, error messages, API references or code +comments. + +If you see text you'd like to improve, use GitHub to search all repositories in the Kubernetes +organization. This can help you figure out where to submit your issue or PR. + +Each repository has its own processes and procedures. Before you file an issue or submit a PR, +read that repository's `README.md`, `CONTRIBUTING.md`, and `code-of-conduct.md`, if they exist. + +Most repositories use issue and PR templates. Have a look through some open issues and PRs to get +a feel for that team's processes. Make sure to fill out the templates with as much detail as +possible when you file issues or PRs. + +## {{% heading "whatsnext" %}} + +- Read [Reviewing](/docs/contribute/review/reviewing-prs) to learn more about the review process. + diff --git a/content/en/docs/Contribute/roles-and-responsibilities.md b/content/en/docs/Contribute/roles-and-responsibilities.md new file mode 100644 index 000000000000..19c9190fd88d --- /dev/null +++ b/content/en/docs/Contribute/roles-and-responsibilities.md @@ -0,0 +1,237 @@ +--- +title: Roles and responsibilities +content_type: concept +weight: 10 +--- + + + +Anyone can contribute to Kubernetes. As your contributions to SIG Docs grow, +you can apply for different levels of membership in the community. +These roles allow you to take on more responsibility within the community. +Each role requires more time and commitment. The roles are: + +- Anyone: regular contributors to the Kubernetes documentation +- Members: can assign and triage issues and provide non-binding review on pull requests +- Reviewers: can lead reviews on documentation pull requests and can vouch for a change's quality +- Approvers: can lead reviews on documentation and merge changes + + + +## Anyone + +Anyone with a GitHub account can contribute to Kubernetes. SIG Docs welcomes all new contributors! + +Anyone can: + +- Open an issue in any [Kubernetes](https://github.com/kubernetes/) + repository, including + [`kubernetes/website`](https://github.com/kubernetes/website) +- Give non-binding feedback on a pull request +- Contribute to a localization +- Suggest improvements on [Slack](https://slack.k8s.io/) or the + [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). + +After [signing the CLA](https://github.com/kubernetes/community/blob/master/CLA.md), anyone can also: + +- Open a pull request to improve existing content, add new content, or write a blog post or case study +- Create diagrams, graphics assets, and embeddable screencasts and videos + +For more information, see [contributing new content](/docs/contribute/new-content/). + +## Members + +A member is someone who has submitted multiple pull requests to +`kubernetes/website`. Members are a part of the +[Kubernetes GitHub organization](https://github.com/kubernetes). + +Members can: + +- Do everything listed under [Anyone](#anyone) +- Use the `/lgtm` comment to add the LGTM (looks good to me) label to a pull request + + {{< note >}} + Using `/lgtm` triggers automation. If you want to provide non-binding + approval, commenting "LGTM" works too! + {{< /note >}} + +- Use the `/hold` comment to block merging for a pull request +- Use the `/assign` comment to assign a reviewer to a pull request +- Provide non-binding review on pull requests +- Use automation to triage and categorize issues +- Document new features + +### Becoming a member + +After submitting at least 5 substantial pull requests and meeting the other +[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#member): + +1. Find two [reviewers](#reviewers) or [approvers](#approvers) to + [sponsor](/docs/contribute/advanced#sponsor-a-new-contributor) your + membership. + + Ask for sponsorship in the [#sig-docs channel on Slack](https://kubernetes.slack.com) or on the + [SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). + + {{< note >}} + Don't send a direct email or Slack direct message to an individual + SIG Docs member. You must request sponsorship before submitting your application. + {{< /note >}} + +1. Open a GitHub issue in the + [`kubernetes/org`](https://github.com/kubernetes/org/) repository. Use the + **Organization Membership Request** issue template. + +1. Let your sponsors know about the GitHub issue. You can either: + - Mention their GitHub username in an issue (`@`) + - Send them the issue link using Slack or email. + + Sponsors will approve your request with a `+1` vote. Once your sponsors + approve the request, a Kubernetes GitHub admin adds you as a member. + Congratulations! + + If your membership request is not accepted you will receive feedback. + After addressing the feedback, apply again. + +1. Accept the invitation to the Kubernetes GitHub organization in your email account. + + {{< note >}} + GitHub sends the invitation to the default email address in your account. + {{< /note >}} + +## Reviewers + +Reviewers are responsible for reviewing open pull requests. Unlike member +feedback, the PR author must address reviewer feedback. Reviewers are members of the +[@kubernetes/sig-docs-{language}-reviews](https://github.com/orgs/kubernetes/teams?query=sig-docs) +GitHub team. + +Reviewers can: + +- Do everything listed under [Anyone](#anyone) and [Members](#members) +- Review pull requests and provide binding feedback + + {{< note >}} + To provide non-binding feedback, prefix your comments with a phrase like "Optionally: ". + {{< /note >}} + +- Edit user-facing strings in code +- Improve code comments + +You can be a SIG Docs reviewer, or a reviewer for docs in a specific subject area. + +### Assigning reviewers to pull requests + +Automation assigns reviewers to all pull requests. You can request a +review from a specific person by commenting: `/assign +[@_github_handle]`. + +If the assigned reviewer has not commented on the PR, another reviewer can +step in. You can also assign technical reviewers as needed. + +### Using `/lgtm` + +LGTM stands for "Looks good to me" and indicates that a pull request is +technically accurate and ready to merge. All PRs need a `/lgtm` comment from a +reviewer and a `/approve` comment from an approver to merge. + +A `/lgtm` comment from reviewer is binding and triggers automation that adds the `lgtm` label. + +### Becoming a reviewer + +When you meet the +[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer), +you can become a SIG Docs reviewer. Reviewers in other SIGs must apply +separately for reviewer status in SIG Docs. + +To apply: + +1. Open a pull request that adds your GitHub username to a section of the + [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) file + in the `kubernetes/website` repository. + + {{< note >}} + If you aren't sure where to add yourself, add yourself to `sig-docs-en-reviews`. + {{< /note >}} + +1. Assign the PR to one or more SIG-Docs approvers (usernames listed under + `sig-docs-{language}-owners`). + +If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, +[K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) +assigns and suggests you as a reviewer on new pull requests. + +## Approvers + +Approvers review and approve pull requests for merging. Approvers are members of the +[@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs) +GitHub teams. + +Approvers can do the following: + +- Everything listed under [Anyone](#anyone), [Members](#members) and [Reviewers](#reviewers) +- Publish contributor content by approving and merging pull requests using the `/approve` comment +- Propose improvements to the style guide +- Propose improvements to docs tests +- Propose improvements to the Kubernetes website or other tooling + +If the PR already has a `/lgtm`, or if the approver also comments with +`/lgtm`, the PR merges automatically. A SIG Docs approver should only leave a +`/lgtm` on a change that doesn't need additional technical review. + + +### Approving pull requests + +Approvers and SIG Docs leads are the only ones who can merge pull requests +into the website repository. This comes with certain responsibilities. + +- Approvers can use the `/approve` command, which merges PRs into the repo. + + {{< warning >}} + A careless merge can break the site, so be sure that when you merge something, you mean it. + {{< /warning >}} + +- Make sure that proposed changes meet the + [documentation content guide](/docs/contribute/style/content-guide/). + + If you ever have a question, or you're not sure about something, feel free + to call for additional review. + +- Verify that Netlify tests pass before you `/approve` a PR. + + Netlify tests must pass before approving + +- Visit the Netlify page preview for a PR to make sure things look good before approving. + +- Participate in the + [PR Wrangler rotation schedule](https://github.com/kubernetes/website/wiki/PR-Wranglers) + for weekly rotations. SIG Docs expects all approvers to participate in this + rotation. See [PR wranglers](/docs/contribute/participate/pr-wranglers/). + for more details. + +### Becoming an approver + +When you meet the +[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#approver), +you can become a SIG Docs approver. Approvers in other SIGs must apply +separately for approver status in SIG Docs. + +To apply: + +1. Open a pull request adding yourself to a section of the + [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) + file in the `kubernetes/website` repository. + + {{< note >}} + If you aren't sure where to add yourself, add yourself to `sig-docs-en-owners`. + {{< /note >}} + +2. Assign the PR to one or more current SIG Docs approvers. + +If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, +[@k8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) +assigns and suggests you as a reviewer on new pull requests. + +## {{% heading "whatsnext" %}} + +- Read about [PR wrangling](/docs/contribute/participate/pr-wranglers/), a role all approvers take on rotation. diff --git a/content/en/docs/Contribute/style/_index.md b/content/en/docs/Contribute/style/_index.md new file mode 100644 index 000000000000..d3633b5aaae5 --- /dev/null +++ b/content/en/docs/Contribute/style/_index.md @@ -0,0 +1,7 @@ +--- +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 new file mode 100644 index 000000000000..1bc311fc1f4c --- /dev/null +++ b/content/en/docs/Contribute/style/content-guide.md @@ -0,0 +1,74 @@ +--- +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 new file mode 100644 index 000000000000..351f48fe339d --- /dev/null +++ b/content/en/docs/Contribute/style/content-organization.md @@ -0,0 +1,147 @@ +--- +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 new file mode 100644 index 000000000000..6a0d44828f5a --- /dev/null +++ b/content/en/docs/Contribute/style/diagram-guide.md @@ -0,0 +1,780 @@ +--- +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 new file mode 100644 index 000000000000..9e9f45b0a604 --- /dev/null +++ b/content/en/docs/Contribute/style/hugo-shortcodes/example1.md @@ -0,0 +1,9 @@ +--- +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 new file mode 100644 index 000000000000..bf03fb5d93d6 --- /dev/null +++ b/content/en/docs/Contribute/style/hugo-shortcodes/example2.md @@ -0,0 +1,7 @@ +--- +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 new file mode 100644 index 000000000000..2c8c10309e8a --- /dev/null +++ b/content/en/docs/Contribute/style/hugo-shortcodes/index.md @@ -0,0 +1,410 @@ +--- +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 `
Configuration parameters
` 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 new file mode 100644 index 000000000000..bd4327414a10 --- /dev/null +++ b/content/en/docs/Contribute/style/hugo-shortcodes/podtemplate.json @@ -0,0 +1,22 @@ + { + "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 new file mode 100644 index 000000000000..ada2274d9974 --- /dev/null +++ b/content/en/docs/Contribute/style/page-content-types.md @@ -0,0 +1,218 @@ +--- +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/style-guide.md b/content/en/docs/Contribute/style/style-guide.md new file mode 100644 index 000000000000..b6a881987902 --- /dev/null +++ b/content/en/docs/Contribute/style/style-guide.md @@ -0,0 +1,674 @@ +--- +title: Documentation Style Guide +linktitle: Style guide +content_type: concept +weight: 40 +--- + + +This page gives writing style guidelines for the Kubernetes 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 +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 +or addition, [add it to the agenda](https://bit.ly/sig-docs-agenda) for an upcoming +SIG Docs meeting, and attend the meeting to participate in the discussion. + + + +{{< note >}} +Kubernetes 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 +glossary entries, tabs, and representing feature state. +{{< /note >}} + +## Language + +Kubernetes documentation has been translated into multiple languages +(see [Localization READMEs](https://github.com/kubernetes/website/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 English-language documentation uses U.S. English spelling and grammar. + +{{< comment >}}[If you're localizing this page, you can omit the point about US English.]{{< /comment >}} + +## Documentation formatting standards + +### Use upper camel case for API objects + +When you refer specifically to interacting with an API object, use +[UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), also known as +Pascal case. You may see different capitalization, such as "configMap", +in the [API Reference](/docs/reference/kubernetes-api/). When writing +general documentation, it's better to use upper camel case, calling it "ConfigMap" instead. + +When you are generally discussing an API object, use +[sentence-style capitalization](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization). + +The following examples focus on capitalization. For more information about formatting +API object names, review the related guidance on [Code Style](#code-style-inline-code). + +{{< table caption = "Do and Don't - Use Pascal case for API objects" >}} +Do | Don't +:--| :----- +The HorizontalPodAutoscaler resource is responsible for ... | The Horizontal pod autoscaler is responsible for ... +A PodList object is a list of pods. | A Pod List object is a list of pods. +The Volume object contains a `hostPath` field. | The volume object contains a hostPath field. +Every ConfigMap object is part of a namespace. | Every configMap object is part of a namespace. +For managing confidential data, consider using the Secret API. | For managing confidential data, consider using the secret API. +{{< /table >}} + +### Use angle brackets for placeholders + +Use angle brackets for placeholders. Tell the reader what a placeholder +represents, for example: + +Display information about a pod: + +```shell +kubectl describe pod -n +``` + +If the namespace of the pod is `default`, you can omit the '-n' parameter. + +### Use bold for user interface elements + +{{< table caption = "Do and Don't - Bold interface elements" >}} +Do | Don't +:--| :----- +Click **Fork**. | Click "Fork". +Select **Other**. | Select "Other". +{{< /table >}} + +### Use italics to define or introduce new terms + +{{< table caption = "Do and Don't - Use italics for new terms" >}} +Do | Don't +:--| :----- +A _cluster_ is a set of nodes ... | A "cluster" is a set of nodes ... +These components form the _control plane_. | These components form the **control plane**. +{{< /table >}} + +### Use code style for filenames, directories, and paths + +{{< table caption = "Do and Don't - Use code style for filenames, directories, and paths" >}} +Do | Don't +:--| :----- +Open the `envars.yaml` file. | Open the envars.yaml file. +Go to the `/docs/tutorials` directory. | Go to the /docs/tutorials directory. +Open the `/_data/concepts.yaml` file. | Open the /\_data/concepts.yaml file. +{{< /table >}} + +### Use the international standard for punctuation inside quotes + +{{< table caption = "Do and Don't - Use the international standard for punctuation inside quotes" >}} +Do | Don't +:--| :----- +events are recorded with an associated "stage". | events are recorded with an associated "stage." +The copy is called a "fork". | The copy is called a "fork." +{{< /table >}} + +## Inline code formatting + +### Use code style for inline code, commands, and API objects {#code-style-inline-code} + +For inline code in an HTML document, use the `` tag. In a Markdown +document, use the backtick (`` ` ``). + +{{< table caption = "Do and Don't - Use code style for inline code, commands, and API objects" >}} +Do | Don't +:--| :----- +The `kubectl run` command creates a `Pod`. | The "kubectl run" command creates a pod. +The kubelet on each node acquires a `Lease`… | The kubelet on each node acquires a lease… +A `PersistentVolume` represents durable storage… | A Persistent Volume represents durable storage… +For declarative management, use `kubectl apply`. | For declarative management, use "kubectl apply". +Enclose code samples with triple backticks. (\`\`\`)| Enclose code samples with any other syntax. +Use single backticks to enclose inline code. For example, `var example = true`. | Use two asterisks (`**`) or an underscore (`_`) to enclose inline code. For example, **var example = true**. +Use triple backticks before and after a multi-line block of code for fenced code blocks. | Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations. +Use meaningful variable names that have a context. | Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context. +Remove trailing spaces in the code. | Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well. +{{< /table >}} + +{{< note >}} +The website supports syntax highlighting for code samples, but specifying a language +is optional. Syntax highlighting in the code block should conform to the +[contrast guidelines.](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0&showtechniques=141%2C143#contrast-minimum) +{{< /note >}} + +### Use code style for object field names and namespaces + +{{< table caption = "Do and Don't - Use code style for object field names" >}} +Do | Don't +:--| :----- +Set the value of the `replicas` field in the configuration file. | Set the value of the "replicas" field in the configuration file. +The value of the `exec` field is an ExecAction object. | The value of the "exec" field is an ExecAction object. +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 + +{{< table caption = "Do and Don't - Use code style for Kubernetes command tool and component names" >}} +Do | Don't +:--| :----- +The kubelet preserves node stability. | The `kubelet` preserves node stability. +The `kubectl` handles locating and authenticating to the API server. | The kubectl handles locating and authenticating to the apiserver. +Run the process with the certificate, `kube-apiserver --client-ca-file=FILENAME`. | Run the process with the certificate, kube-apiserver --client-ca-file=FILENAME. | +{{< /table >}} + +### Starting a sentence with a component tool or component name + +{{< table caption = "Do and Don't - Starting a sentence with a component tool or component name" >}} +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. +{{< /table >}} + +### Use a general descriptor over a component name + +{{< 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. +Aggregated APIs are subordinate API servers. | Aggregated APIs are subordinate APIServers. +{{< /table >}} + +### Use normal style for string and integer field values + +For field values of type string or integer, use normal style without quotation marks. + +{{< table caption = "Do and Don't - Use normal style for string and integer field values" >}} +Do | Don't +:--| :----- +Set the value of `imagePullPolicy` to Always. | Set the value of `imagePullPolicy` to "Always". +Set the value of `image` to nginx:1.16. | Set the value of `image` to `nginx:1.16`. +Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`. +{{< /table >}} + +## Referring to Kubernetes 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`, +`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 + +The different Kubernetes 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. + +Always use "resource" or "object" when referring to an API resource in docs. +For example, use "a `Secret` object" over just "a `Secret`". + +### API resource names + +Always format API resource names using [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), +also known as PascalCase, and code formatting. + +For inline code in an HTML document, use the `` tag. In a Markdown document, use the backtick (`` ` ``). + +Don't split an API object name into separate words. For example, use `PodTemplateList`, not Pod Template List. + +For more information about PascalCase and code formatting, please review the related guidance on +[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). + +## Code snippet formatting + +### Don't include the command prompt + +{{< table caption = "Do and Don't - Don't include the command prompt" >}} +Do | Don't +:--| :----- +kubectl get pods | $ kubectl get pods +{{< /table >}} + +### Separate commands from output + +Verify that the pod is running on your chosen node: + +```shell +kubectl get pods --output=wide +``` + +The output is similar to this: + +```console +NAME READY STATUS RESTARTS AGE IP NODE +nginx 1/1 Running 0 13s 10.200.0.4 worker0 +``` + +### Versioning Kubernetes 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 +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 +`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, +the front-matter of your markdown file should look something like: + +```yaml +--- +title: +min-kubernetes-server-version: v1.8 +--- +``` + +In code and configuration examples, do not include comments about alternative versions. +Be careful to not include incorrect statements in your examples as comments, such as: + +```yaml +apiVersion: v1 # earlier versions use... +kind: Pod +... +``` + +## Kubernetes.io word list + +A list of Kubernetes-specific terms and words to be used consistently across the site. + +{{< table caption = "Kubernetes.io word list" >}} +Term | Usage +:--- | :---- +Kubernetes | Kubernetes 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. +{{< /table >}} + +## Shortcodes + +Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create +different rhetorical appeal levels. Our documentation supports three different +shortcodes in this category: **Note** `{{}}`, +**Caution** `{{}}`, and **Warning** `{{}}`. + +1. Surround the text with an opening and closing shortcode. + +2. Use the following syntax to apply a style: + + ```none + {{}} + No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.) + {{}} + ``` + + The output is: + + {{< note >}} + The prefix you choose is the same text for the tag. + {{< /note >}} + +### Note + +Use `{{}}` to highlight a tip or a piece of information that may be helpful to know. + +For example: + +``` +{{}} +You can _still_ use Markdown inside these callouts. +{{}} +``` + +The output is: + +{{< note >}} +You can _still_ use Markdown inside these callouts. +{{< /note >}} + +You can use a `{{}}` in a list: + +``` +1. Use the note shortcode in a list + +1. A second item with an embedded note + + {{}} + Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues). + {{}} + +1. A third item in a list + +1. A fourth item in a list +``` + +The output is: + +1. Use the note shortcode in a list + +1. A second item with an embedded note + + {{< note >}} + Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues). + {{< /note >}} + +1. A third item in a list + +1. A fourth item in a list + +### Caution + +Use `{{}}` to call attention to an important piece of information to avoid pitfalls. + +For example: + +``` +{{}} +The callout style only applies to the line directly above the tag. +{{}} +``` + +The output is: + +{{< caution >}} +The callout style only applies to the line directly above the tag. +{{< /caution >}} + +### Warning + +Use `{{}}` to indicate danger or a piece of information that is crucial to follow. + +For example: + +``` +{{}} +Beware. +{{}} +``` + +The output is: + +{{< warning >}} +Beware. +{{< /warning >}} + +## Common Shortcode Issues + +### Ordered Lists + +Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag. + +For example: + + 1. Preheat oven to 350˚F + + 1. Prepare the batter, and pour into springform pan. + {{}}Grease the pan for best results.{{}} + + 1. Bake for 20-25 minutes or until set. + +The output is: + +1. Preheat oven to 350˚F + +1. Prepare the batter, and pour into springform pan. + + {{< note >}}Grease the pan for best results.{{< /note >}} + +1. Bake for 20-25 minutes or until set. + +### Include Statements + +Shortcodes inside include statements will break the build. You must insert them +in the parent document, before and after you call the include. For example: + +``` +{{}} +{{}} +{{}} +``` + +## Markdown elements + +### Line breaks + +Use a single newline to separate block-level content like headings, lists, images, +code blocks, and others. The exception is second-level headings, where it should +be two newlines. Second-level headings follow the first-level (or the title) without +any preceding paragraphs or texts. A two line spacing helps visualize the overall +structure of content in a code editor better. + +Manually wrap paragraphs in the Markdown source when appropriate. Since the git +tool and the GitHub website generate file diffs on a line-by-line basis, +manually wrapping long lines helps the reviewers to easily find out the changes +made in a PR and provide feedback. It also helps the downstream localization +teams where people track the upstream changes on a per-line basis. Line +wrapping can happen at the end of a sentence or a punctuation character, for +example. One exception to this is that a Markdown link or a shortcode is +expected to be in a single line. + +### Headings and titles {#headings} + +People accessing this documentation may use a screen reader or other assistive technology (AT). +[Screen readers](https://en.wikipedia.org/wiki/Screen_reader) are linear output devices, +they output items on a page one at a time. If there is a lot of content on a page, you can +use headings to give the page an internal structure. A good page structure helps all readers +to easily navigate the page or filter topics of interest. + +{{< table caption = "Do and Don't - Headings" >}} +Do | Don't +:--| :----- +Update the title in the front matter of the page or blog post. | Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading. +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` +{{< /table >}} + +### Paragraphs + +{{< table caption = "Do and Don't - Paragraphs" >}} +Do | Don't +:--| :----- +Try to keep paragraphs under 6 sentences. | Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it. +Use three hyphens (`---`) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section. | Use horizontal rules for decoration. +{{< /table >}} + +### Links + +{{< table caption = "Do and Don't - Links" >}} +Do | Don't +:--| :----- +Write hyperlinks that give you context for the content they link to. For example: Certain ports are open on your machines. See Check required ports for more details. | Use ambiguous terms such as "click here". For example: Certain ports are open on your machines. See here for more details. +Write Markdown-style links: `[link text](URL)`. For example: `[Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions)` and the output is [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions). | Write HTML-style links: `Visit our tutorial!`, or create links that open in new tabs or windows. For example: `[example website](https://example.com){target="_blank"}` +{{< /table >}} + +### Lists + +Group items in a list that are related to each other and need to appear in a specific +order or to indicate a correlation between multiple items. When a screen reader comes +across a list—whether it is an ordered or unordered list—it will be announced to the +user that there is a group of list items. The user can then use the arrow keys to move +up and down between the various items in the list. Website navigation links can also be +marked up as list items; after all they are nothing but a group of related links. + +- End each item in a list with a period if one or more items in the list are complete + sentences. For the sake of consistency, normally either all items or none should be complete sentences. + + {{< note >}} + Ordered lists that are part of an incomplete introductory sentence can be in lowercase + and punctuated as if each item was a part of the introductory sentence. + {{< /note >}} + +- Use the number one (`1.`) for ordered lists. + +- Use (`+`), (`*`), or (`-`) for unordered lists. + +- Leave a blank line after each list. + +- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅). + +- List items may consist of multiple paragraphs. Each subsequent paragraph in a list + item must be indented by either four spaces or one tab. + +### Tables + +The semantic purpose of a data table is to present tabular data. Sighted users can +quickly scan the table but a screen reader goes through line by line. A table caption +is used to create a descriptive title for a data table. Assistive technologies (AT) +use the HTML table caption element to identify the table contents to the user within the page structure. + +- Add table captions using [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions) for tables. + +## Content best practices + +This section contains suggested best practices for clear, concise, and consistent content. + +### Use present tense + +{{< table caption = "Do and Don't - Use present tense" >}} +Do | Don't +:--| :----- +This command starts a proxy. | This command will start a proxy. + {{< /table >}} + +Exception: Use future or past tense if it is required to convey the correct +meaning. + +### Use active voice + +{{< table caption = "Do and Don't - Use active voice" >}} +Do | Don't +:--| :----- +You can explore the API using a browser. | The API can be explored using a browser. +The YAML file specifies the replica count. | The replica count is specified in the YAML file. +{{< /table >}} + +Exception: Use passive voice if active voice leads to an awkward construction. + +### Use simple and direct language + +Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." + +{{< table caption = "Do and Don't - Use simple and direct language" >}} +Do | Don't +:--| :----- +To create a ReplicaSet, ... | In order to create a ReplicaSet, ... +See the configuration file. | Please see the configuration file. +View the pods. | With this next command, we'll view the pods. +{{< /table >}} + +### Address the reader as "you" + +{{< table caption = "Do and Don't - Addressing the reader" >}} +Do | Don't +:--| :----- +You can create a Deployment by ... | We'll create a Deployment by ... +In the preceding output, you can see... | In the preceding output, we can see ... +{{< /table >}} + +### Avoid Latin phrases + +Prefer English terms over Latin abbreviations. + +{{< table caption = "Do and Don't - Avoid Latin phrases" >}} +Do | Don't +:--| :----- +For example, ... | e.g., ... +That is, ...| i.e., ... +{{< /table >}} + +Exception: Use "etc." for et cetera. + +## Patterns to avoid + +### Avoid using "we" + +Using "we" in a sentence can be confusing, because the reader might not know +whether they're part of the "we" you're describing. + +{{< table caption = "Do and Don't - Patterns to avoid" >}} +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 ... +This page teaches you how to use pods. | In this page, we are going to learn about pods. +{{< /table >}} + +### Avoid jargon and idioms + +Some readers speak English as a second language. Avoid jargon and idioms to help them understand better. + +{{< table caption = "Do and Don't - Avoid jargon and idioms" >}} +Do | Don't +:--| :----- +Internally, ... | Under the hood, ... +Create a new cluster. | Turn up a new cluster. +{{< /table >}} + +### Avoid statements about the future + +Avoid making promises or giving hints about the future. If you need to talk about +an alpha feature, put the text under a heading that identifies it as alpha +information. + +An exception to this rule is documentation about announced deprecations +targeting removal in future versions. One example of documentation like this +is the [Deprecated API migration guide](/docs/reference/using-api/deprecation-guide/). + +### Avoid statements that will soon be out of date + +Avoid words like "currently" and "new." A feature that is new today might not be +considered new in a few months. + +{{< table caption = "Do and Don't - Avoid statements that will soon be out of date" >}} +Do | Don't +:--| :----- +In version 1.4, ... | In the current version, ... +The Federation feature provides ... | The new Federation feature provides ... +{{< /table >}} + +### Avoid words that assume a specific level of understanding + +Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value. + +{{< table caption = "Do and Don't - Avoid insensitive words" >}} +Do | Don't +:--| :----- +Include one command in ... | Include just one command in ... +Run the container ... | Simply run the container ... +You can remove ... | You can easily remove ... +These steps ... | These simple steps ... +{{< /table >}} + +### EditorConfig file +The Kubernetes 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. + +## {{% heading "whatsnext" %}} + +* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/). +* Learn about [using page templates](/docs/contribute/style/page-content-types/). +* Learn about [custom hugo shortcodes](/docs/contribute/style/hugo-shortcodes/). +* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/). diff --git a/content/en/docs/Contribute/style/write-new-topic.md b/content/en/docs/Contribute/style/write-new-topic.md new file mode 100644 index 000000000000..4204e937dda1 --- /dev/null +++ b/content/en/docs/Contribute/style/write-new-topic.md @@ -0,0 +1,170 @@ +--- +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/). + diff --git a/content/en/docs/Contribute/suggesting-improvements.md b/content/en/docs/Contribute/suggesting-improvements.md new file mode 100644 index 000000000000..aac6ce1c1351 --- /dev/null +++ b/content/en/docs/Contribute/suggesting-improvements.md @@ -0,0 +1,67 @@ +--- +title: Suggesting content improvements +content_type: concept +weight: 10 +card: + name: contribute + weight: 15 + anchors: + - anchor: "#opening-an-issue" + title: Suggest content improvements +--- + + + +If you notice an issue with Kubernetes documentation or have an idea for new content, then open an issue. All you need is a [GitHub account](https://github.com/join) and a web browser. + +In most cases, new work on Kubernetes documentation begins with an issue in GitHub. Kubernetes contributors +then review, categorize and tag issues as needed. Next, you or another member +of the Kubernetes community open a pull request with changes to resolve the issue. + + + + + +## Opening an issue + +If you want to suggest improvements to existing content or notice an error, then open an issue. + +1. Click the **Create an issue** link on the right sidebar. This redirects you + to a GitHub issue page pre-populated with some headers. +2. Describe the issue or suggestion for improvement. Provide as many details as you can. +3. Click **Submit new issue**. + +After submitting, check in on your issue occasionally or turn on GitHub notifications. +Reviewers and other community members might ask questions before +they can take action on your issue. + +## Suggesting new content + +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 an issue**. +- Go to [GitHub](https://github.com/kubernetes/website/issues/new/) and file the issue directly. + +## How to file great issues + + +Keep the following in mind when filing an issue: + +- Provide a clear issue description. Describe what specifically is missing, out of date, + wrong, or needs improvement. +- Explain the specific impact the issue has on users. +- Limit the scope of a given issue to a reasonable unit of work. For problems + with a large scope, break them down into smaller issues. For example, "Fix the security docs" + is too broad, but "Add details to the 'Restricting network access' topic" is specific enough + to be actionable. +- Search the existing issues to see if there's anything related or similar to the + new issue. +- If the new issue relates to another issue or pull request, refer to it + either by its full URL or by the issue or pull request number prefixed + with a `#` character. For example, `Introduced by #987654`. +- Follow the [Code of Conduct](/community/code-of-conduct/). Respect your +fellow contributors. For example, "The docs are terrible" is not + helpful or polite feedback. + + From a2c04d2bb8ac5101f0ed2db50aeab78db8cd8ed3 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 12:59:24 +0100 Subject: [PATCH 26/62] Main contribution guide --- content/en/docs/Contribute/_index.md | 484 +++++++++++++- .../{new-content => }/blogs-case-studies.md | 0 .../Contribute/new-content/new-features.md | 143 ---- .../docs/Contribute/new-content/open-a-pr.md | 628 ------------------ .../Contribute/roles-and-responsibilities.md | 237 ------- .../Contribute/suggesting-improvements.md | 67 -- 6 files changed, 476 insertions(+), 1083 deletions(-) rename content/en/docs/Contribute/{new-content => }/blogs-case-studies.md (100%) delete mode 100644 content/en/docs/Contribute/new-content/new-features.md delete mode 100644 content/en/docs/Contribute/new-content/open-a-pr.md delete mode 100644 content/en/docs/Contribute/roles-and-responsibilities.md delete mode 100644 content/en/docs/Contribute/suggesting-improvements.md diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 851cc0199d80..b80faf030304 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -5,8 +5,9 @@ weight: 200 cSpell:ignore: --- -This website is maintained by -[OpenTelemetry SIG Comms](/docs/contribute/#get-involved-with-sig-comms). +You can open an issue about OpenTelemetry documentation, or contribute a change +with a pull request (PR) to the +[`open-telemetry/opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). OpenTelemetry documentation contributors: @@ -20,17 +21,13 @@ See also the general , which provides details on the Contributor License Agreement and the Code of Conduct. -## Get started - -You can open an issue about OpenTelemetry documentation, or contribute a change -with a pull request (PR) to the -[`open-telemetry/opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). +## Requirements To contribute, you need to be familiar with the following techs and tools: * [git](https://git-scm.com/) * [GitHub](https://lab.github.com/) -* Markdown +* Markdown (CommonMark) * YAML For technical details concerning how the documentation is built and tested @@ -38,6 +35,477 @@ locally, see the [CONTRIBUTING.md](https://github.com/open-telemetry/opentelemetry.io/blob/main/CONTRIBUTING.md) file. +### Sign the CNCF CLA {#sign-the-cla} + +All OpenTelemetry contributors must read the +[Contributor guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) +and +[sign the Contributor License Agreement (CLA)](https://docs.linuxfoundation.org/lfx/easycla/contributors) +. + +Pull requests from contributors who haven't signed the CLA fail the automated +tests. The name and email you provide must match those found in +your `git config`, and your git name and email must match those used for the +CNCF CLA. + +## Contribute new content + +{{< mermaid >}} +flowchart LR + subgraph first[How to contribute] + direction TB + T[ ] -.- + A[Sign the CNCF CLA] --> D[Write docs in markdown
and build site with Hugo] + D[Write docs in markdown
and build site with Hugo] --- E[Push source to GitHub] + E --- G[Open a pull request] + end + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,B,C,D,E,F,G,H grey +class S,T spacewhite +class first,second white +{{}} + +***Figure - Contributing new content*** + +The previous figure presents the basic steps for new docs contributions. + +To contribute new content pages or improve existing content pages, open a pull +request (PR): + +- If your change is small, or you're unfamiliar with Git, read +[Changes using GitHub](#changes-using-github) to learn how to edit a page. +- If your changes are large, read [Work from a local fork](#fork-the-repo) to learn how to make +changes locally on your computer. + +### Changes using GitHub {#changes-using-github} + +If you're less experienced with Git workflows, here's an easier method of +opening a pull request. Figure 1 outlines the steps and the details follow. + +{{< mermaid >}} +flowchart LR +A([fa:fa-user New
Contributor]) --- id1[(open-telemetry/opentelemetry.io
GitHub)] +subgraph tasks[Changes using GitHub] +direction TB + 0[ ] -.- + 1[1. Edit this page] --> 2[2. Use GitHub markdown
editor to make changes] + 2 --> 3[3. fill in Propose file change] + +end +subgraph tasks2[ ] +direction TB +4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] +6 --> 7[7. select Create pull request] +end + +id1 --> tasks --> tasks2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class A,1,2,3,4,5,6,7 grey +class 0 spacewhite +class tasks,tasks2 white +class id1 k8s +{{}} + +Figure 1. Steps for opening a PR using GitHub. + +1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. + +1. Make your changes in the GitHub editor. + +1. Below the editor, fill in the **Propose file change** form. + +1. Select **Propose file change**. + +1. Select **Create pull request**. + +1. The **Open a pull request** screen appears. Your description helps reviewers understand your change. + +1. Select **Create pull request**. + +Before merging a pull request, OpenTelemetry community members review and +approve it. If you have someone in mind, leave a comment with their GitHub +username in it. + +If a reviewer asks you to make changes: + +1. Go to the **Files changed** tab. +1. Select the pencil (edit) icon on any files changed by the pull request. +1. Make the changes requested. +1. Commit the changes. + +When your review is complete, a reviewer merges your PR and your changes go liv +a few minutes later. + +### Work from a local fork {#fork-the-repo} + +If you're more experienced with Git, or if your changes are larger than a few +lines, work from a local fork. + +Make sure you have +[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed +on your computer. You can also use a user interface for Git. + +Figure 2 shows the steps to follow when you work from a local fork. The details +for each step follow. + +{{< mermaid >}} +flowchart LR +1[Fork the open-telemetry/opentelemetry
repository] --> 2[Create local clone
and set upstream] +subgraph changes[Your changes] +direction TB +S[ ] -.- +3[Create a branch
example: my_new_branch] --> 3a[Make changes using
a text editor] --> 4["Preview your changes
locally using Hugo
(localhost:1313)"] +end +subgraph changes2[Commit / Push] +direction TB +T[ ] -.- +5[Commit your changes] --> 6[Push commit to
origin/my_new_branch] +end + +2 --> changes --> changes2 + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; +classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 +class 1,2,3,3a,4,5,6 grey +class S,T spacewhite +class changes,changes2 white +{{}} + +Figure 2. Working from a local fork to make your changes. + +#### Fork the kubernetes/website repository + +1. Navigate to the [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) repository. +1. Select **Fork**. + +#### Create a local clone and set the upstream + +1. In a terminal window, clone your fork and install the requirements: + + ```shell + git clone git@github.com:/opentelemetry.io.git + cd opentelemetry.io + npm install + ``` + +1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream` remote: + + ```shell + git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git + ``` + +1. Confirm your `origin` and `upstream` repositories: + + ```shell + git remote -v + ``` + + Output is similar to: + + ```none + origin git@github.com:/opentelemetry.io.git (fetch) + origin git@github.com:/opentelemetry.io.git (push) + upstream https://github.com/open-telemetry/opentelemetry.io.git (fetch) + upstream https://github.com/open-telemetry/opentelemetry.io.git (push) + ``` + +1. Fetch commits from your fork's `origin/main` and `open-telemetry/opentelemetry.io`'s `upstream/main`: + + ```shell + git fetch origin + git fetch upstream + ``` + + This makes sure your local repository is up to date before you start making changes. + +#### Create a branch + +1. Create a new branch. This example assumes the base branch is `upstream/main`: + + ```shell + git checkout -b upstream/main + ``` + +1. Make your changes using a code or text editor. + +At any time, use the `git status` command to see what files you've changed. + +#### Commit your changes + +When you are ready to submit a pull request, commit your changes. + +1. In your local repository, check which files you need to commit: + + ```shell + git status + ``` + + Output is similar to: + + ```none + On branch + Your branch is up to date with 'origin/'. + + Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: content/en/docs/contribute/new-content/contributing-content.md + + no changes added to commit (use "git add" and/or "git commit -a") + ``` + +1. Add the files listed under **Changes not staged for commit** to the commit: + + ```shell + git add + ``` + + Repeat this for each file. + +1. After adding all the files, create a commit: + + ```shell + git commit -m "Your commit message" + ``` + +1. Push your local branch and its new commit to your remote fork: + + ```shell + git push origin + ``` + +#### Preview your changes locally {#preview-locally} + +Preview your changes locally before pushing them or opening a pull request. +A preview lets you catch build errors or markdown formatting problems. + +To build and serve the site locally with Hugo, run the following command: + +```shell +npm run serve +``` + +Navigate to `https://localhost:1313` in your web browser to see the local +preview. Hugo watches the changes and rebuilds the site as needed. + +To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or +close the terminal window. + +#### Open a pull request from your fork {#open-a-pr} + +Figure 3 shows the steps to open a PR from your fork to the +[open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) +. + +{{< mermaid >}} +flowchart LR +subgraph first[ ] +direction TB +1[1. Go to open-telemetry/opentelemetry.io repository] --> 2[2. Select New Pull Request] +2 --> 3[3. Select compare across forks] +3 --> 4[4. Select your fork from
head repository drop-down menu] +end +subgraph second [ ] +direction TB +5[5. Select your branch from
the compare drop-down menu] --> 6[6. Select Create Pull Request] +6 --> 7[7. Add a description
to your PR] +7 --> 8[8. Select Create pull request] +end + +first --> second + +classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; +classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold +class 1,2,3,4,5,6,7,8 grey +class first,second white +{{}} + +Figure 3. Steps to open a PR from your fork to the +[open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). + +1. In a web browser, go to the [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) repository. +1. Select **New Pull Request**. +1. Select **compare across forks**. +1. From the **head repository** drop-down menu, select your fork. +1. From the **compare** drop-down menu, select your branch. +1. Select **Create Pull Request**. +1. Add a description for your pull request: + + - **Title** (50 characters or less): Summarize the intent of the change. + - **Description**: Describe the change in more detail. + + - If there is a related GitHub issue, include `Fixes #12345` or `Closes #12345` in the + description. GitHub's automation closes the mentioned issue after merging the PR if used. + If there are other related PRs, link those as well. + - If you want advice on something specific, include any questions you'd like reviewers to + think about in your description. + +1. Select the **Create pull request** button. + +Your pull request is available in +[Pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls). + +After opening a PR, GitHub runs automated tests and tries to deploy a preview using +[Netlify](https://www.netlify.com/). + +- If the Netlify build fails, select **Details** for more information. +- If the Netlify build succeeds, select **Details** opens a staged version of the OpenTelemetry + website with your changes applied. This is how reviewers check your changes. + +GitHub also automatically assigns labels to a PR to help reviewers. + +#### Changes from reviewers + +Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits. + +1. Fetch commits from your remote fork and rebase your working branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + +1. After rebasing, force-push new changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +#### Merge conflicts and rebasing + +If another contributor commits changes to the same file in another PR, it can +create a merge conflict. You must resolve all merge conflicts in your PR. + +1. Update your fork and rebase your local branch: + + ```shell + git fetch origin + git rebase origin/ + ``` + + Then force-push the changes to your fork: + + ```shell + git push --force-with-lease origin + ``` + +1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and rebase your branch: + + ```shell + git fetch upstream + git rebase upstream/main + ``` + +1. Inspect the results of the rebase: + + ```shell + git status + ``` + + This results in a number of files marked as conflicted. + +1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. + Resolve the conflict and delete the conflict marker. + + {{< note >}} + For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). + {{< /note >}} + +1. Add the files to the changeset: + + ```shell + git add + ``` + +1. Continue the rebase: + + ```shell + git rebase --continue + ``` + +1. Repeat steps 2 to 5 as needed. + + After applying all commits, the `git status` command shows that the rebase is complete. + +1. Force-push the branch to your fork: + + ```shell + git push --force-with-lease origin + ``` + + The pull request no longer shows any conflicts. + +## Contribute to other repos + +The [Kubernetes 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. + +If you see text you'd like to improve, use GitHub to search all repositories in +the OpenTelemetry organization. This can help you figure out where to submit +your issue or PR. + +Each repository has its own processes and procedures. Before you file an issue +or submit a PR, read that repository's `README.md`, `CONTRIBUTING.md`, and +`code-of-conduct.md`, if they exist. + +Most repositories use issue and PR templates. Have a look through some open +issues and PRs to get a feel for that team's processes. Make sure to fill out +the templates with as much detail as possible when you file issues or PRs. + +## Open an issue + +If you want to suggest improvements to existing content or notice an error, +open an issue. + +1. Click the **Create documentation issue** link on the right sidebar. This redirects you + to a GitHub issue page prepopulated with some headers. +2. Describe the issue or suggestion for improvement. Provide as many details as you can. +3. Click **Submit new issue**. + +After submitting, check in on your issue occasionally or turn on GitHub +notifications. Reviewers and other community members might ask questions before +they can take action on your issue. + +### Suggesting new content + +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. + +## How to file great issues + +Keep the following in mind when filing an issue: + +- Provide a clear issue description. Describe what specifically is missing, out of date, + wrong, or needs improvement. +- Explain the specific impact the issue has on users. +- Limit the scope of a given issue to a reasonable unit of work. For problems + with a large scope, break them down into smaller issues. For example, "Fix the security docs" + is too broad, but "Add details to the 'Restricting network access' topic" is specific enough + to be actionable. +- Search the existing issues to see if there's anything related or similar to the + new issue. +- If the new issue relates to another issue or pull request, refer to it + either by its full URL or by the issue or pull request number prefixed + with a `#` character. For example, `Introduced by #987654`. +- Follow the [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). Respect your +fellow contributors. For example, "The docs are terrible" is not + helpful or polite feedback. + + ## Other ways to contribute - Visit the [OpenTelemetry community site](/community/). diff --git a/content/en/docs/Contribute/new-content/blogs-case-studies.md b/content/en/docs/Contribute/blogs-case-studies.md similarity index 100% rename from content/en/docs/Contribute/new-content/blogs-case-studies.md rename to content/en/docs/Contribute/blogs-case-studies.md diff --git a/content/en/docs/Contribute/new-content/new-features.md b/content/en/docs/Contribute/new-content/new-features.md deleted file mode 100644 index 3b71e2d5316d..000000000000 --- a/content/en/docs/Contribute/new-content/new-features.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Documenting a feature for a release -linktitle: Documenting for a release -content_type: concept -main_menu: true -weight: 20 -card: - name: contribute - weight: 45 - title: Documenting a feature for a release ---- - - -Each major Kubernetes release introduces new features that require documentation. New releases also bring updates to existing features and documentation (such as upgrading a feature from alpha to beta). - -Generally, the SIG responsible for a feature submits draft documentation of the -feature as a pull request to the appropriate development branch of the -`kubernetes/website` repository, and someone on the SIG Docs team provides -editorial feedback or edits the draft directly. This section covers the branching -conventions and process used during a release by both groups. - - - - - -## For documentation contributors - -In general, documentation contributors don't write content from scratch for a release. -Instead, they work with the SIG creating a new feature to refine the draft documentation and make it release ready. - -After you've chosen a feature to document or assist, ask about it in the `#sig-docs` -Slack channel, in a weekly SIG Docs meeting, or directly on the PR filed by the -feature SIG. If you're given the go-ahead, you can edit into the PR using one of -the techniques described in -[Commit into another person's PR](/docs/contribute/review/for-approvers/#commit-into-another-person-s-pr). - -### Find out about upcoming features - -To find out about upcoming features, attend the weekly SIG Release meeting (see -the [community](/community/) page for upcoming meetings) -and monitor the release-specific documentation -in the [kubernetes/sig-release](https://github.com/kubernetes/sig-release/) -repository. Each release has a sub-directory in the [/sig-release/tree/master/releases/](https://github.com/kubernetes/sig-release/tree/master/releases) -directory. The sub-directory contains a release schedule, a draft of the release -notes, and a document listing each person on the release team. - -The release schedule contains links to all other documents, meetings, -meeting minutes, and milestones relating to the release. It also contains -information about the goals and timeline of the release, and any special -processes in place for this release. Near the bottom of the document, several -release-related terms are defined. - -This document also contains a link to the **Feature tracking sheet**, which is -the official way to find out about all new features scheduled to go into the -release. - -The release team document lists who is responsible for each release role. If -it's not clear who to talk to about a specific feature or question you have, -either attend the release meeting to ask your question, or contact the release -lead so that they can redirect you. - -The release notes draft is a good place to find out about -specific features, changes, deprecations, and more about the release. The -content is not finalized until late in the release cycle, so use caution. - -### Feature tracking sheet - -The feature tracking sheet [for a given Kubernetes release](https://github.com/kubernetes/sig-release/tree/master/releases) -lists each feature that is planned for a release. -Each line item includes the name of the feature, a link to the feature's main -GitHub issue, its stability level (Alpha, Beta, or Stable), the SIG and -individual responsible for implementing it, whether it -needs docs, a draft release note for the feature, and whether it has been -merged. Keep the following in mind: - -- Beta and Stable features are generally a higher documentation priority than - Alpha features. -- It's hard to test (and therefore to document) a feature that hasn't been merged, - or is at least considered feature-complete in its PR. -- Determining whether a feature needs documentation is a manual process. Even if - a feature is not marked as needing docs, you may need to document the feature. - -## For developers or other SIG members - -This section is information for members of other Kubernetes SIGs documenting new features -for a release. - -If you are a member of a SIG developing a new feature for Kubernetes, you need -to work with SIG Docs to be sure your feature is documented in time for the -release. Check the -[feature tracking spreadsheet](https://github.com/kubernetes/sig-release/tree/master/releases) -or check in the `#sig-release` Kubernetes Slack channel to verify scheduling details and -deadlines. - -### Open a placeholder PR - -1. Open a **draft** pull request against the -`dev-{{< skew nextMinorVersion >}}` branch in the `kubernetes/website` repository, with a small -commit that you will amend later. To create a draft pull request, use the -Create Pull Request drop-down and select **Create Draft Pull Request**, -then click **Draft Pull Request**. -2. Edit the pull request description to include links to [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) -PR(s) and [kubernetes/enhancements](https://github.com/kubernetes/enhancements) issue(s). -3. Leave a comment on the related [kubernetes/enhancements](https://github.com/kubernetes/enhancements) -issue with a link to the PR to notify the docs person managing this release that -the feature docs are coming and should be tracked for the release. - -If your feature does not need -any documentation changes, make sure the sig-release team knows this, by -mentioning it in the `#sig-release` Slack channel. If the feature does need -documentation but the PR is not created, the feature may be removed from the -milestone. - -### PR ready for review - -When ready, populate your placeholder PR with feature documentation and change -the state of the PR from draft to **ready for review**. To mark a pull request -as ready for review, navigate to the merge box and click **Ready for review**. - -Do your best to describe your feature and how to use it. If you need help structuring your documentation, ask in the `#sig-docs` Slack channel. - -When you complete your content, the documentation person assigned to your feature reviews it. -To ensure technical accuracy, the content may also require a technical review from corresponding SIG(s). -Use their suggestions to get the content to a release ready state. - -If your feature is an Alpha or Beta feature and is behind a feature gate, -make sure you add it to [Alpha/Beta Feature gates](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features) -table as part of your pull request. With new feature gates, a description of -the feature gate is also required. If your feature is GA'ed or deprecated, -make sure to move it from the -[Feature gates for Alpha/Feature](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features) table -to [Feature gates for graduated or deprecated features](/docs/reference/command-line-tools-reference/feature-gates-removed/#feature-gates-that-are-removed) -table with Alpha and Beta history intact. - -If your feature needs documentation and the first draft -content is not received, the feature may be removed from the milestone. - -### All PRs reviewed and ready to merge - -If your PR has not yet been merged into the `dev-{{< skew nextMinorVersion >}}` branch by the release deadline, work with the -docs person managing the release to get it in by the deadline. If your feature needs -documentation and the docs are not ready, the feature may be removed from the -milestone. \ No newline at end of file diff --git a/content/en/docs/Contribute/new-content/open-a-pr.md b/content/en/docs/Contribute/new-content/open-a-pr.md deleted file mode 100644 index 382befe11694..000000000000 --- a/content/en/docs/Contribute/new-content/open-a-pr.md +++ /dev/null @@ -1,628 +0,0 @@ ---- -title: Opening a pull request -content_type: concept -weight: 10 -card: - name: contribute - weight: 40 ---- - - - -{{< note >}} -**Code developers**: If you are documenting a new feature for an -upcoming Kubernetes release, see -[Document a new feature](/docs/contribute/new-content/new-features/). -{{< /note >}} - -To contribute new content pages or improve existing content pages, open a pull request (PR). -Make sure you follow all the requirements in the -[Before you begin](/docs/contribute/new-content/) section. - -If your change is small, or you're unfamiliar with git, read -[Changes using GitHub](#changes-using-github) to learn how to edit a page. - -If your changes are large, read [Work from a local fork](#fork-the-repo) to learn how to make -changes locally on your computer. - - - -## Changes using GitHub - -If you're less experienced with git workflows, here's an easier method of -opening a pull request. Figure 1 outlines the steps and the details follow. - - - - -{{< mermaid >}} -flowchart LR -A([fa:fa-user New
Contributor]) --- id1[(kubernetes/website
GitHub)] -subgraph tasks[Changes using GitHub] -direction TB - 0[ ] -.- - 1[1. Edit this page] --> 2[2. Use GitHub markdown
editor to make changes] - 2 --> 3[3. fill in Propose file change] - -end -subgraph tasks2[ ] -direction TB -4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] -6 --> 7[7. select Create pull request] -end - -id1 --> tasks --> tasks2 - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; -classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 -class A,1,2,3,4,5,6,7 grey -class 0 spacewhite -class tasks,tasks2 white -class id1 k8s -{{}} - -Figure 1. Steps for opening a PR using GitHub. - -1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. - -1. Make your changes in the GitHub markdown editor. - -1. Below the editor, fill in the **Propose file change** form. - In the first field, give your commit message a title. - In the second field, provide a description. - - {{< note >}} - Do not use any [GitHub Keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) - in your commit message. You can add those to the pull request description later. - {{< /note >}} - -1. Select **Propose file change**. - -1. Select **Create pull request**. - -1. The **Open a pull request** screen appears. Fill in the form: - - - The **Subject** field of the pull request defaults to the commit summary. - You can change it if needed. - - The **Body** contains your extended commit message, if you have one, - and some template text. Add the - details the template text asks for, then delete the extra template text. - - Leave the **Allow edits from maintainers** checkbox selected. - - {{< note >}} - PR descriptions are a great way to help reviewers understand your change. - For more information, see [Opening a PR](#open-a-pr). - {{}} - -1. Select **Create pull request**. - -### Addressing feedback in GitHub - -Before merging a pull request, Kubernetes community members review and -approve it. The `k8s-ci-robot` suggests reviewers based on the nearest -owner mentioned in the pages. If you have someone specific in mind, -leave a comment with their GitHub username in it. - -If a reviewer asks you to make changes: - -1. Go to the **Files changed** tab. -1. Select the pencil (edit) icon on any files changed by the pull request. -1. Make the changes requested. -1. Commit the changes. - -If you are waiting on a reviewer, reach out once every 7 days. You can also post a message in the -`#sig-docs` Slack channel. - -When your review is complete, a reviewer merges your PR and your changes go live a few minutes later. - -## Work from a local fork {#fork-the-repo} - -If you're more experienced with git, or if your changes are larger than a few lines, -work from a local fork. - -Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed -on your computer. You can also use a git UI application. - -Figure 2 shows the steps to follow when you work from a local fork. The details for each step follow. - - - - -{{< mermaid >}} -flowchart LR -1[Fork the kubernetes/website
repository] --> 2[Create local clone
and set upstream] -subgraph changes[Your changes] -direction TB -S[ ] -.- -3[Create a branch
example: my_new_branch] --> 3a[Make changes using
text editor] --> 4["Preview your changes
locally using Hugo
(localhost:1313)
or build container image"] -end -subgraph changes2[Commit / Push] -direction TB -T[ ] -.- -5[Commit your changes] --> 6[Push commit to
origin/my_new_branch] -end - -2 --> changes --> changes2 - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; -classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 -class 1,2,3,3a,4,5,6 grey -class S,T spacewhite -class changes,changes2 white -{{}} - -Figure 2. Working from a local fork to make your changes. - -### Fork the kubernetes/website repository - -1. Navigate to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository. -1. Select **Fork**. - -### Create a local clone and set the upstream - -1. In a terminal window, clone your fork and update the [Docsy Hugo theme](https://github.com/google/docsy#readme): - - ```shell - git clone git@github.com:/website - cd website - git submodule update --init --recursive --depth 1 - ``` - -1. Navigate to the new `website` directory. Set the `kubernetes/website` repository as the `upstream` remote: - - ```shell - cd website - - git remote add upstream https://github.com/kubernetes/website.git - ``` - -1. Confirm your `origin` and `upstream` repositories: - - ```shell - git remote -v - ``` - - Output is similar to: - - ```none - origin git@github.com:/website.git (fetch) - origin git@github.com:/website.git (push) - upstream https://github.com/kubernetes/website.git (fetch) - upstream https://github.com/kubernetes/website.git (push) - ``` - -1. Fetch commits from your fork's `origin/main` and `kubernetes/website`'s `upstream/main`: - - ```shell - git fetch origin - git fetch upstream - ``` - - This makes sure your local repository is up to date before you start making changes. - - {{< note >}} - This workflow is different than the - [Kubernetes Community GitHub Workflow](https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md). - You do not need to merge your local copy of `main` with `upstream/main` before pushing updates - to your fork. - {{< /note >}} - -### Create a branch - -1. Decide which branch base to your work on: - - - For improvements to existing content, use `upstream/main`. - - For new content about existing features, use `upstream/main`. - - For localized content, use the localization's conventions. For more information, see - [localizing Kubernetes documentation](/docs/contribute/localization/). - - For new features in an upcoming Kubernetes release, use the feature branch. For more - information, see [documenting for a release](/docs/contribute/new-content/new-features/). - - For long-running efforts that multiple SIG Docs contributors collaborate on, - like content reorganization, use a specific feature branch created for that effort. - - If you need help choosing a branch, ask in the `#sig-docs` Slack channel. - -1. Create a new branch based on the branch identified in step 1. This example assumes the base - branch is `upstream/main`: - - ```shell - git checkout -b upstream/main - ``` - -1. Make your changes using a text editor. - -At any time, use the `git status` command to see what files you've changed. - -### Commit your changes - -When you are ready to submit a pull request, commit your changes. - -1. In your local repository, check which files you need to commit: - - ```shell - git status - ``` - - Output is similar to: - - ```none - On branch - Your branch is up to date with 'origin/'. - - Changes not staged for commit: - (use "git add ..." to update what will be committed) - (use "git checkout -- ..." to discard changes in working directory) - - modified: content/en/docs/contribute/new-content/contributing-content.md - - no changes added to commit (use "git add" and/or "git commit -a") - ``` - -1. Add the files listed under **Changes not staged for commit** to the commit: - - ```shell - git add - ``` - - Repeat this for each file. - -1. After adding all the files, create a commit: - - ```shell - git commit -m "Your commit message" - ``` - - {{< note >}} - Do not use any [GitHub Keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) - in your commit message. You can add those to the pull request - description later. - {{< /note >}} - -1. Push your local branch and its new commit to your remote fork: - - ```shell - git push origin - ``` - -### Preview your changes locally {#preview-locally} - -It's a good idea to preview your changes locally before pushing them or opening a pull request. -A preview lets you catch build errors or markdown formatting problems. - -You can either build the website's container image or run Hugo locally. Building the container -image is slower but displays [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/), which can -be useful for debugging. - -{{< tabs name="tab_with_hugo" >}} -{{% tab name="Hugo in a container" %}} - -{{< note >}} -The commands below use Docker as default container engine. Set the `CONTAINER_ENGINE` environment -variable to override this behaviour. -{{< /note >}} - -1. Build the container image locally - _You only need this step if you are testing a change to the Hugo tool itself_ - - ```shell - # Run this in a terminal (if required) - make container-image - ``` - -1. Start Hugo in a container: - - ```shell - # Run this in a terminal - make container-serve - ``` - -1. In a web browser, navigate to `https://localhost:1313`. Hugo watches the - changes and rebuilds the site as needed. - -1. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, - or close the terminal window. - -{{% /tab %}} -{{% tab name="Hugo on the command line" %}} - -Alternately, install and use the `hugo` command on your computer: - -1. Install the [Hugo](https://gohugo.io/getting-started/installing/) version specified in - [`website/netlify.toml`](https://raw.githubusercontent.com/kubernetes/website/main/netlify.toml). - -1. If you have not updated your website repository, the `website/themes/docsy` directory is empty. - The site cannot build without a local copy of the theme. To update the website theme, run: - - ```shell - git submodule update --init --recursive --depth 1 - ``` - -1. In a terminal, go to your Kubernetes website repository and start the Hugo server: - - ```shell - cd /website - hugo server --buildFuture - ``` - -1. In a web browser, navigate to `https://localhost:1313`. Hugo watches the - changes and rebuilds the site as needed. - -1. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, - or close the terminal window. - -{{% /tab %}} -{{< /tabs >}} - -### Open a pull request from your fork to kubernetes/website {#open-a-pr} - -Figure 3 shows the steps to open a PR from your fork to the [kubernetes/website](https://github.com/kubernetes/website). The details follow. - -Please, note that contributors can mention `kubernetes/website` as `k/website`. - - - - -{{< mermaid >}} -flowchart LR -subgraph first[ ] -direction TB -1[1. Go to kubernetes/website repository] --> 2[2. Select New Pull Request] -2 --> 3[3. Select compare across forks] -3 --> 4[4. Select your fork from
head repository drop-down menu] -end -subgraph second [ ] -direction TB -5[5. Select your branch from
the compare drop-down menu] --> 6[6. Select Create Pull Request] -6 --> 7[7. Add a description
to your PR] -7 --> 8[8. Select Create pull request] -end - -first --> second - -classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; -classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold -class 1,2,3,4,5,6,7,8 grey -class first,second white -{{}} - -Figure 3. Steps to open a PR from your fork to the [kubernetes/website](https://github.com/kubernetes/website). - -1. In a web browser, go to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository. -1. Select **New Pull Request**. -1. Select **compare across forks**. -1. From the **head repository** drop-down menu, select your fork. -1. From the **compare** drop-down menu, select your branch. -1. Select **Create Pull Request**. -1. Add a description for your pull request: - - - **Title** (50 characters or less): Summarize the intent of the change. - - **Description**: Describe the change in more detail. - - - If there is a related GitHub issue, include `Fixes #12345` or `Closes #12345` in the - description. GitHub's automation closes the mentioned issue after merging the PR if used. - If there are other related PRs, link those as well. - - If you want advice on something specific, include any questions you'd like reviewers to - think about in your description. - -1. Select the **Create pull request** button. - -Congratulations! Your pull request is available in [Pull requests](https://github.com/kubernetes/website/pulls). - -After opening a PR, GitHub runs automated tests and tries to deploy a preview using -[Netlify](https://www.netlify.com/). - -- If the Netlify build fails, select **Details** for more information. -- If the Netlify build succeeds, select **Details** opens a staged version of the Kubernetes - website with your changes applied. This is how reviewers check your changes. - -GitHub also automatically assigns labels to a PR, to help reviewers. You can add them too, if -needed. For more information, see [Adding and removing issue labels](/docs/contribute/review/for-approvers/#adding-and-removing-issue-labels). - -### Addressing feedback locally - -1. After making your changes, amend your previous commit: - - ```shell - git commit -a --amend - ``` - - - `-a`: commits all changes - - `--amend`: amends the previous commit, rather than creating a new one - -1. Update your commit message if needed. - -1. Use `git push origin ` to push your changes and re-run the Netlify tests. - - {{< note >}} - If you use `git commit -m` instead of amending, you must [squash your commits](#squashing-commits) - before merging. - {{< /note >}} - -#### Changes from reviewers - -Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits. - -1. Fetch commits from your remote fork and rebase your working branch: - - ```shell - git fetch origin - git rebase origin/ - ``` - -1. After rebasing, force-push new changes to your fork: - - ```shell - git push --force-with-lease origin - ``` - -#### Merge conflicts and rebasing - -{{< note >}} -For more information, see [Git Branching - Basic Branching and Merging](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts), -[Advanced Merging](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging), or ask in the -`#sig-docs` Slack channel for help. -{{< /note >}} - -If another contributor commits changes to the same file in another PR, it can create a merge -conflict. You must resolve all merge conflicts in your PR. - -1. Update your fork and rebase your local branch: - - ```shell - git fetch origin - git rebase origin/ - ``` - - Then force-push the changes to your fork: - - ```shell - git push --force-with-lease origin - ``` - -1. Fetch changes from `kubernetes/website`'s `upstream/main` and rebase your branch: - - ```shell - git fetch upstream - git rebase upstream/main - ``` - -1. Inspect the results of the rebase: - - ```shell - git status - ``` - - This results in a number of files marked as conflicted. - -1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. - Resolve the conflict and delete the conflict marker. - - {{< note >}} - For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). - {{< /note >}} - -1. Add the files to the changeset: - - ```shell - git add - ``` - -1. Continue the rebase: - - ```shell - git rebase --continue - ``` - -1. Repeat steps 2 to 5 as needed. - - After applying all commits, the `git status` command shows that the rebase is complete. - -1. Force-push the branch to your fork: - - ```shell - git push --force-with-lease origin - ``` - - The pull request no longer shows any conflicts. - -### Squashing commits - -{{< note >}} -For more information, see [Git Tools - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History), -or ask in the `#sig-docs` Slack channel for help. -{{< /note >}} - -If your PR has multiple commits, you must squash them into a single commit before merging your PR. -You can check the number of commits on your PR's **Commits** tab or by running the `git log` -command locally. - -{{< note >}} -This topic assumes `vim` as the command line text editor. -{{< /note >}} - -1. Start an interactive rebase: - - ```shell - git rebase -i HEAD~ - ``` - - Squashing commits is a form of rebasing. The `-i` switch tells git you want to rebase interactively. - `HEAD~}} - For more information, see [Interactive Mode](https://git-scm.com/docs/git-rebase#_interactive_mode). - {{< /note >}} - -1. Start editing the file. - - Change the original text: - - ```none - pick d875112ca Original commit - pick 4fa167b80 Address feedback 1 - pick 7d54e15ee Address feedback 2 - ``` - - To: - - ```none - pick d875112ca Original commit - squash 4fa167b80 Address feedback 1 - squash 7d54e15ee Address feedback 2 - ``` - - This squashes commits `4fa167b80 Address feedback 1` and `7d54e15ee Address feedback 2` into - `d875112ca Original commit`, leaving only `d875112ca Original commit` as a part of the timeline. - -1. Save and exit your file. - -1. Push your squashed commit: - - ```shell - git push --force-with-lease origin - ``` - -## Contribute to other repos - -The [Kubernetes project](https://github.com/kubernetes) contains 50+ repositories. Many of these -repositories contain documentation: user-facing help text, error messages, API references or code -comments. - -If you see text you'd like to improve, use GitHub to search all repositories in the Kubernetes -organization. This can help you figure out where to submit your issue or PR. - -Each repository has its own processes and procedures. Before you file an issue or submit a PR, -read that repository's `README.md`, `CONTRIBUTING.md`, and `code-of-conduct.md`, if they exist. - -Most repositories use issue and PR templates. Have a look through some open issues and PRs to get -a feel for that team's processes. Make sure to fill out the templates with as much detail as -possible when you file issues or PRs. - -## {{% heading "whatsnext" %}} - -- Read [Reviewing](/docs/contribute/review/reviewing-prs) to learn more about the review process. - diff --git a/content/en/docs/Contribute/roles-and-responsibilities.md b/content/en/docs/Contribute/roles-and-responsibilities.md deleted file mode 100644 index 19c9190fd88d..000000000000 --- a/content/en/docs/Contribute/roles-and-responsibilities.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Roles and responsibilities -content_type: concept -weight: 10 ---- - - - -Anyone can contribute to Kubernetes. As your contributions to SIG Docs grow, -you can apply for different levels of membership in the community. -These roles allow you to take on more responsibility within the community. -Each role requires more time and commitment. The roles are: - -- Anyone: regular contributors to the Kubernetes documentation -- Members: can assign and triage issues and provide non-binding review on pull requests -- Reviewers: can lead reviews on documentation pull requests and can vouch for a change's quality -- Approvers: can lead reviews on documentation and merge changes - - - -## Anyone - -Anyone with a GitHub account can contribute to Kubernetes. SIG Docs welcomes all new contributors! - -Anyone can: - -- Open an issue in any [Kubernetes](https://github.com/kubernetes/) - repository, including - [`kubernetes/website`](https://github.com/kubernetes/website) -- Give non-binding feedback on a pull request -- Contribute to a localization -- Suggest improvements on [Slack](https://slack.k8s.io/) or the - [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). - -After [signing the CLA](https://github.com/kubernetes/community/blob/master/CLA.md), anyone can also: - -- Open a pull request to improve existing content, add new content, or write a blog post or case study -- Create diagrams, graphics assets, and embeddable screencasts and videos - -For more information, see [contributing new content](/docs/contribute/new-content/). - -## Members - -A member is someone who has submitted multiple pull requests to -`kubernetes/website`. Members are a part of the -[Kubernetes GitHub organization](https://github.com/kubernetes). - -Members can: - -- Do everything listed under [Anyone](#anyone) -- Use the `/lgtm` comment to add the LGTM (looks good to me) label to a pull request - - {{< note >}} - Using `/lgtm` triggers automation. If you want to provide non-binding - approval, commenting "LGTM" works too! - {{< /note >}} - -- Use the `/hold` comment to block merging for a pull request -- Use the `/assign` comment to assign a reviewer to a pull request -- Provide non-binding review on pull requests -- Use automation to triage and categorize issues -- Document new features - -### Becoming a member - -After submitting at least 5 substantial pull requests and meeting the other -[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#member): - -1. Find two [reviewers](#reviewers) or [approvers](#approvers) to - [sponsor](/docs/contribute/advanced#sponsor-a-new-contributor) your - membership. - - Ask for sponsorship in the [#sig-docs channel on Slack](https://kubernetes.slack.com) or on the - [SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). - - {{< note >}} - Don't send a direct email or Slack direct message to an individual - SIG Docs member. You must request sponsorship before submitting your application. - {{< /note >}} - -1. Open a GitHub issue in the - [`kubernetes/org`](https://github.com/kubernetes/org/) repository. Use the - **Organization Membership Request** issue template. - -1. Let your sponsors know about the GitHub issue. You can either: - - Mention their GitHub username in an issue (`@`) - - Send them the issue link using Slack or email. - - Sponsors will approve your request with a `+1` vote. Once your sponsors - approve the request, a Kubernetes GitHub admin adds you as a member. - Congratulations! - - If your membership request is not accepted you will receive feedback. - After addressing the feedback, apply again. - -1. Accept the invitation to the Kubernetes GitHub organization in your email account. - - {{< note >}} - GitHub sends the invitation to the default email address in your account. - {{< /note >}} - -## Reviewers - -Reviewers are responsible for reviewing open pull requests. Unlike member -feedback, the PR author must address reviewer feedback. Reviewers are members of the -[@kubernetes/sig-docs-{language}-reviews](https://github.com/orgs/kubernetes/teams?query=sig-docs) -GitHub team. - -Reviewers can: - -- Do everything listed under [Anyone](#anyone) and [Members](#members) -- Review pull requests and provide binding feedback - - {{< note >}} - To provide non-binding feedback, prefix your comments with a phrase like "Optionally: ". - {{< /note >}} - -- Edit user-facing strings in code -- Improve code comments - -You can be a SIG Docs reviewer, or a reviewer for docs in a specific subject area. - -### Assigning reviewers to pull requests - -Automation assigns reviewers to all pull requests. You can request a -review from a specific person by commenting: `/assign -[@_github_handle]`. - -If the assigned reviewer has not commented on the PR, another reviewer can -step in. You can also assign technical reviewers as needed. - -### Using `/lgtm` - -LGTM stands for "Looks good to me" and indicates that a pull request is -technically accurate and ready to merge. All PRs need a `/lgtm` comment from a -reviewer and a `/approve` comment from an approver to merge. - -A `/lgtm` comment from reviewer is binding and triggers automation that adds the `lgtm` label. - -### Becoming a reviewer - -When you meet the -[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer), -you can become a SIG Docs reviewer. Reviewers in other SIGs must apply -separately for reviewer status in SIG Docs. - -To apply: - -1. Open a pull request that adds your GitHub username to a section of the - [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) file - in the `kubernetes/website` repository. - - {{< note >}} - If you aren't sure where to add yourself, add yourself to `sig-docs-en-reviews`. - {{< /note >}} - -1. Assign the PR to one or more SIG-Docs approvers (usernames listed under - `sig-docs-{language}-owners`). - -If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, -[K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) -assigns and suggests you as a reviewer on new pull requests. - -## Approvers - -Approvers review and approve pull requests for merging. Approvers are members of the -[@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs) -GitHub teams. - -Approvers can do the following: - -- Everything listed under [Anyone](#anyone), [Members](#members) and [Reviewers](#reviewers) -- Publish contributor content by approving and merging pull requests using the `/approve` comment -- Propose improvements to the style guide -- Propose improvements to docs tests -- Propose improvements to the Kubernetes website or other tooling - -If the PR already has a `/lgtm`, or if the approver also comments with -`/lgtm`, the PR merges automatically. A SIG Docs approver should only leave a -`/lgtm` on a change that doesn't need additional technical review. - - -### Approving pull requests - -Approvers and SIG Docs leads are the only ones who can merge pull requests -into the website repository. This comes with certain responsibilities. - -- Approvers can use the `/approve` command, which merges PRs into the repo. - - {{< warning >}} - A careless merge can break the site, so be sure that when you merge something, you mean it. - {{< /warning >}} - -- Make sure that proposed changes meet the - [documentation content guide](/docs/contribute/style/content-guide/). - - If you ever have a question, or you're not sure about something, feel free - to call for additional review. - -- Verify that Netlify tests pass before you `/approve` a PR. - - Netlify tests must pass before approving - -- Visit the Netlify page preview for a PR to make sure things look good before approving. - -- Participate in the - [PR Wrangler rotation schedule](https://github.com/kubernetes/website/wiki/PR-Wranglers) - for weekly rotations. SIG Docs expects all approvers to participate in this - rotation. See [PR wranglers](/docs/contribute/participate/pr-wranglers/). - for more details. - -### Becoming an approver - -When you meet the -[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#approver), -you can become a SIG Docs approver. Approvers in other SIGs must apply -separately for approver status in SIG Docs. - -To apply: - -1. Open a pull request adding yourself to a section of the - [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES) - file in the `kubernetes/website` repository. - - {{< note >}} - If you aren't sure where to add yourself, add yourself to `sig-docs-en-owners`. - {{< /note >}} - -2. Assign the PR to one or more current SIG Docs approvers. - -If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, -[@k8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) -assigns and suggests you as a reviewer on new pull requests. - -## {{% heading "whatsnext" %}} - -- Read about [PR wrangling](/docs/contribute/participate/pr-wranglers/), a role all approvers take on rotation. diff --git a/content/en/docs/Contribute/suggesting-improvements.md b/content/en/docs/Contribute/suggesting-improvements.md deleted file mode 100644 index aac6ce1c1351..000000000000 --- a/content/en/docs/Contribute/suggesting-improvements.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Suggesting content improvements -content_type: concept -weight: 10 -card: - name: contribute - weight: 15 - anchors: - - anchor: "#opening-an-issue" - title: Suggest content improvements ---- - - - -If you notice an issue with Kubernetes documentation or have an idea for new content, then open an issue. All you need is a [GitHub account](https://github.com/join) and a web browser. - -In most cases, new work on Kubernetes documentation begins with an issue in GitHub. Kubernetes contributors -then review, categorize and tag issues as needed. Next, you or another member -of the Kubernetes community open a pull request with changes to resolve the issue. - - - - - -## Opening an issue - -If you want to suggest improvements to existing content or notice an error, then open an issue. - -1. Click the **Create an issue** link on the right sidebar. This redirects you - to a GitHub issue page pre-populated with some headers. -2. Describe the issue or suggestion for improvement. Provide as many details as you can. -3. Click **Submit new issue**. - -After submitting, check in on your issue occasionally or turn on GitHub notifications. -Reviewers and other community members might ask questions before -they can take action on your issue. - -## Suggesting new content - -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 an issue**. -- Go to [GitHub](https://github.com/kubernetes/website/issues/new/) and file the issue directly. - -## How to file great issues - - -Keep the following in mind when filing an issue: - -- Provide a clear issue description. Describe what specifically is missing, out of date, - wrong, or needs improvement. -- Explain the specific impact the issue has on users. -- Limit the scope of a given issue to a reasonable unit of work. For problems - with a large scope, break them down into smaller issues. For example, "Fix the security docs" - is too broad, but "Add details to the 'Restricting network access' topic" is specific enough - to be actionable. -- Search the existing issues to see if there's anything related or similar to the - new issue. -- If the new issue relates to another issue or pull request, refer to it - either by its full URL or by the issue or pull request number prefixed - with a `#` character. For example, `Introduced by #987654`. -- Follow the [Code of Conduct](/community/code-of-conduct/). Respect your -fellow contributors. For example, "The docs are terrible" is not - helpful or polite feedback. - - From e5cb9cb6292e98d3b83338a8da1e2fb46234c5b5 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 13:06:32 +0100 Subject: [PATCH 27/62] Blog post guide --- content/en/docs/Contribute/_index.md | 2 +- .../en/docs/Contribute/blogs-case-studies.md | 181 +++--------------- 2 files changed, 32 insertions(+), 151 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index b80faf030304..2924b4410bd4 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -510,5 +510,5 @@ fellow contributors. For example, "The docs are terrible" is not - Visit the [OpenTelemetry community site](/community/). - Add your application to the [Registry](/ecosystem). -- Submit a [blog post or case study](/docs/contribute/new-content/blogs-case-studies/). +- Submit a [blog post or case study](/docs/contribute/blogs-case-studies/). diff --git a/content/en/docs/Contribute/blogs-case-studies.md b/content/en/docs/Contribute/blogs-case-studies.md index 72d234e7a84b..7c855689b959 100644 --- a/content/en/docs/Contribute/blogs-case-studies.md +++ b/content/en/docs/Contribute/blogs-case-studies.md @@ -1,58 +1,45 @@ --- -title: Submitting blog posts and case studies -linktitle: Blogs and case studies +title: Submit a blog post +linktitle: Submit a blog post slug: blogs-case-studies -content_type: concept weight: 30 +cSpell:ignore: --- +The [OpenTelemetry blog](/blog/) communicates new features, community reports, +and any news that might be relevant to the OpenTelemetry community. This +includes end users and developers. Anyone can write a blog post and submit it +for review. - +## Submit a post -Anyone can write a blog post and submit it for review. -Case studies require extensive review before they're approved. +Blog posts should not be commercial in nature and should consist of original +content that applies broadly to the OpenTelemetry community. Appropriate blog +content includes: - - -## The Kubernetes Blog - -The Kubernetes blog is used by the project to communicate new features, community reports, and any -news that might be relevant to the Kubernetes community. This includes end users and developers. -Most of the blog's content is about things happening in the core project, but we encourage you to -submit about things happening elsewhere in the ecosystem too! - -Anyone can write a blog post and submit it for review. - -### Submit a Post - -Blog posts should not be commercial in nature and should consist of original content that applies -broadly to the Kubernetes community. Appropriate blog content includes: - -- New Kubernetes capabilities -- Kubernetes projects updates +- New OpenTelemetry capabilities +- OpenTelemetry projects updates - Updates from Special Interest Groups - Tutorials and walkthroughs -- Thought leadership around Kubernetes -- Kubernetes Partner OSS integration -- **Original content only** +- Thought leadership around OpenTelemetry +- OpenTelemetry Partner OSS integration Unsuitable content includes: - Vendor product pitches - Partner updates without an integration and customer story -- Syndicated posts (language translations ok) To submit a blog post, follow these steps: -1. [Sign the CLA](https://github.com/kubernetes/community/blob/master/CLA.md) +1. [Sign the CLA](https://docs.linuxfoundation.org/lfx/easycla/contributors) if you have not yet done so. 1. Have a look at the Markdown format for existing blog posts in the - [website repository](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts). + [opentelemetry.io repository](https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/blog). 1. Write out your blog post in a text editor of your choice. -1. On the same link from step 2, click the Create new file button. Paste your content into the editor. +1. On the same link from step 2, select **Create new file**. Paste your content into the editor. Name the file to match the proposed title of the blog post, but don’t put the date in the file name. The blog reviewers will work with you on the final file name and the date the blog will be published. @@ -61,139 +48,33 @@ To submit a blog post, follow these steps: 1. A blog post reviewer will review your submission and work with you on feedback and final details. When the blog post is approved, the blog will be scheduled for publication. -### Guidelines and expectations +## Guidelines and expectations - Blog posts should not be vendor pitches. - - Articles must contain content that applies broadly to the Kubernetes community. For example, a - submission should focus on upstream Kubernetes as opposed to vendor-specific configurations. + - Articles must contain content that applies broadly to the OpenTelemetry community. For example, a + submission should focus on upstream OpenTelemetry as opposed to vendor-specific configurations. Check the [Documentation style guide](/docs/contribute/style/content-guide/#what-s-allowed) for - what is typically allowed on Kubernetes properties. - - Links should primarily be to the official Kubernetes documentation. When using external + what is typically allowed on OpenTelemetry properties. + - Links should primarily be to the official OpenTelemetry documentation. When using external references, links should be diverse - For example a submission shouldn't contain only links back to a single company's blog. - - Sometimes this is a delicate balance. The [blog team](https://kubernetes.slack.com/messages/sig-docs-blog/) - is there to give guidance on whether a post is appropriate for the Kubernetes blog, so don't - hesitate to reach out. - Blog posts are not published on specific dates. - - Articles are reviewed by community volunteers. We'll try our best to accommodate specific + - Articles are reviewed by community volunteers. We'll try our best to accommodate specific timing, but we make no guarantees. - - Many core parts of the Kubernetes projects submit blog posts during release windows, delaying + - Many core parts of the OpenTelemetry projects submit blog posts during release windows, delaying publication times. Consider submitting during a quieter period of the release cycle. - If you are looking for greater coordination on post release dates, coordinating with [CNCF marketing](https://www.cncf.io/about/contact/) is a more appropriate choice than submitting a blog post. - - Sometimes reviews can get backed up. If you feel your review isn't getting the attention it needs, - you can reach out to the blog team on the [`#sig-docs-blog` Slack channel](https://kubernetes.slack.com/messages/sig-docs-blog/) - to ask in real time. -- Blog posts should be relevant to Kubernetes users. +- Blog posts should be relevant to OpenTelemetry users. - - Topics related to participation in or results of Kubernetes SIGs activities are always on - topic (see the work in the [Contributor Comms Team](https://github.com/kubernetes/community/blob/master/communication/contributor-comms/blogging-resources/blog-guidelines.md#contributor-comms-blog-guidelines) - for support on these posts). - - The components of Kubernetes are purposely modular, so tools that use existing integration - points like CNI and CSI are on topic. + - Topics related to participation in or results of OpenTelemetry SIGs activities are always on + topic. - Posts about other CNCF projects may or may not be on topic. We recommend asking the blog team before submitting a draft. - - Many CNCF projects have their own blog. These are often a better choice for posts. There are - times of major feature or milestone for a CNCF project that users would be interested in - reading on the Kubernetes blog. - - Blog posts about contributing to the Kubernetes project should be in the - [Kubernetes Contributors site](https://kubernetes.dev) - -- Blog posts should be original content - - - The official blog is not for repurposing existing content from a third party as new content. - - The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows - commercial use of the content for commercial purposes, but not the other way around. - -- Blog posts should aim to be future proof - - - Given the development velocity of the project, we want evergreen content that won't require - updates to stay accurate for the reader. - - It can be a better choice to add a tutorial or update official documentation than to write a - high level overview as a blog post. - - Consider concentrating the long technical content as a call to action of the blog post, and - focus on the problem space or why readers should care. - -### Technical Considerations for submitting a blog post - -Submissions need to be in Markdown format to be used by the [Hugo](https://gohugo.io/) generator -for the blog. There are [many resources available](https://gohugo.io/documentation/) on how to use -this technology stack. - -We recognize that this requirement makes the process more difficult for less-familiar folks to -submit, and we're constantly looking at solutions to lower this bar. If you have ideas on how to -lower the barrier, please volunteer to help out. - -The SIG Docs [blog subproject](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject) -manages the review process for blog posts. For more information, see -[Submit a post](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject#submit-a-post). - -To submit a blog post follow these directions: - -- [Open a pull request](/docs/contribute/new-content/open-a-pr/#fork-the-repo) with a new blog post. - New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/main/content/en/blog/_posts) - directory. - -- Ensure that your blog post follows the correct naming conventions and the following frontmatter - (metadata) information: - - - The Markdown file name must follow the format `YYYY-MM-DD-Your-Title-Here.md`. For example, - `2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md`. - - Do **not** include dots in the filename. A name like `2020-01-01-whats-new-in-1.19.md` causes - failures during a build. - - The front matter must include the following: - - ```yaml - --- - layout: blog - title: "Your Title Here" - date: YYYY-MM-DD - slug: text-for-URL-link-here-no-spaces - --- - ``` - - - The first or initial commit message should be a short summary of the work being done and - should stand alone as a description of the blog post. Please note that subsequent edits to - your blog will be squashed into this main commit, so it should be as useful as possible. - - - Examples of a good commit message: - - _Add blog post on the foo kubernetes feature_ - - _blog: foobar announcement_ - - Examples of bad commit message: - - _Add blog post_ - - _._ - - _initial commit_ - - _draft post_ - - - The blog team will then review your PR and give you comments on things you might need to fix. - After that the bot will merge your PR and your blog post will be published. - - - If the content of the blog post contains only content that is not expected to require updates - to stay accurate for the reader, it can be marked as evergreen and exempted from the automatic - warning about outdated content added to blog posts older than one year. - - - To mark a blog post as evergreen, add this to the front matter: - - ```yaml - evergreen: true - ``` - - Examples of content that should not be marked evergreen: - - **Tutorials** that only apply to specific releases or versions and not all future versions - - References to pre-GA APIs or features - -## Submit a case study - -Case studies highlight how organizations are using Kubernetes to solve real-world problems. The -Kubernetes marketing team and members of the {{< glossary_tooltip text="CNCF" term_id="cncf" >}} -collaborate with you on all case studies. - -Have a look at the source for the -[existing case studies](https://github.com/kubernetes/website/tree/main/content/en/case-studies). - -Refer to the [case study guidelines](https://github.com/cncf/foundation/blob/master/case-study-guidelines.md) -and submit your request as outlined in the guidelines. - + - Many CNCF projects have their own blog. These are often a better choice for posts. There are + times of major feature or milestone for a CNCF project that users would be interested in + reading on the OpenTelemetry blog. From e6cc3dbfbbfb4a8fb3140a75764ce151ffaf0780 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 5 Dec 2023 13:18:43 +0100 Subject: [PATCH 28/62] 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 `
Configuration parameters
` 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/). - From 78e3220a9e8bb2cccf6d52359aa2c1f7f31c4cb3 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Mon, 11 Dec 2023 16:25:13 +0100 Subject: [PATCH 29/62] Edits --- content/en/docs/Contribute/style-guide.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index 01a4e22a7e86..c6b0adf7bbb6 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -6,7 +6,6 @@ cSpell:ignore: slug: style-guide --- - 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. From 3fa6bd4c9b290d95b655e5d974e1663ba5a0a4ec Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Mon, 11 Dec 2023 17:11:56 +0100 Subject: [PATCH 30/62] Fix errors --- content/en/docs/Contribute/_index.md | 160 +++-- .../en/docs/Contribute/blogs-case-studies.md | 62 +- content/en/docs/Contribute/style-guide.md | 677 +----------------- 3 files changed, 136 insertions(+), 763 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index c03fc9aa3ddc..8ccc13bbf113 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -2,7 +2,7 @@ title: Contribute description: Learn how to contribute to the OpenTelemetry documentation. weight: 200 -cSpell:ignore: +cSpell:ignore: --- You can open an issue about OpenTelemetry documentation, or contribute a change @@ -25,10 +25,10 @@ Conduct. To contribute, you need to be familiar with the following techs and tools: -* [git](https://git-scm.com/) -* [GitHub](https://lab.github.com/) -* Markdown (CommonMark) -* YAML +- [git](https://git-scm.com/) +- [GitHub](https://lab.github.com/) +- Markdown (CommonMark) +- YAML For technical details concerning how the documentation is built and tested locally, see the @@ -44,14 +44,14 @@ and . Pull requests from contributors who haven't signed the CLA fail the automated -tests. The name and email you provide must match those found in -your `git config`, and your git name and email must match those used for the -CNCF CLA. +tests. The name and email you provide must match those found in your +`git config`, and your git name and email must match those used for the CNCF +CLA. ## Contribute new content -{{< mermaid >}} -flowchart LR +```mermaid +flowchart LR subgraph first[How to contribute] direction TB T[ ] -.- @@ -66,9 +66,9 @@ classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,B,C,D,E,F,G,H grey class S,T spacewhite class first,second white -{{}} +``` -***Figure - Contributing new content*** +**_Figure - Contributing new content_** The previous figure presents the basic steps for new docs contributions. @@ -76,16 +76,16 @@ To contribute new content pages or improve existing content pages, open a pull request (PR): - If your change is small, or you're unfamiliar with Git, read -[Changes using GitHub](#changes-using-github) to learn how to edit a page. -- If your changes are large, read [Work from a local fork](#fork-the-repo) to learn how to make -changes locally on your computer. + [Changes using GitHub](#changes-using-github) to learn how to edit a page. +- If your changes are large, read [Work from a local fork](#fork-the-repo) to + learn how to make changes locally on your computer. ### Changes using GitHub {#changes-using-github} If you're less experienced with Git workflows, here's an easier method of opening a pull request. Figure 1 outlines the steps and the details follow. -{{< mermaid >}} +```mermaid flowchart LR A([fa:fa-user New
Contributor]) --- id1[(open-telemetry/opentelemetry.io
GitHub)] subgraph tasks[Changes using GitHub] @@ -98,7 +98,7 @@ end subgraph tasks2[ ] direction TB 4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request] -6 --> 7[7. select Create pull request] +6 --> 7[7. select Create pull request] end id1 --> tasks --> tasks2 @@ -111,11 +111,12 @@ class A,1,2,3,4,5,6,7 grey class 0 spacewhite class tasks,tasks2 white class id1 k8s -{{}} +``` Figure 1. Steps for opening a PR using GitHub. -1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. +1. On the page where you see the issue, select the **Edit this page** option in + the right-hand side navigation panel. 1. Make your changes in the GitHub editor. @@ -125,7 +126,8 @@ Figure 1. Steps for opening a PR using GitHub. 1. Select **Create pull request**. -1. The **Open a pull request** screen appears. Your description helps reviewers understand your change. +1. The **Open a pull request** screen appears. Your description helps reviewers + understand your change. 1. Select **Create pull request**. @@ -155,7 +157,7 @@ on your computer. You can also use a user interface for Git. Figure 2 shows the steps to follow when you work from a local fork. The details for each step follow. -{{< mermaid >}} +```mermaid flowchart LR 1[Fork the open-telemetry/opentelemetry
repository] --> 2[Create local clone
and set upstream] subgraph changes[Your changes] @@ -178,13 +180,15 @@ classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class 1,2,3,3a,4,5,6 grey class S,T spacewhite class changes,changes2 white -{{}} +``` Figure 2. Working from a local fork to make your changes. #### Fork the open-telemetry/opentelemetry.io repository -1. Navigate to the [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) repository. +1. Navigate to the + [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) + repository. 1. Select **Fork**. #### Create a local clone and set the upstream @@ -197,7 +201,8 @@ Figure 2. Working from a local fork to make your changes. npm install ``` -1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream` remote: +1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream` + remote: ```shell git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git @@ -218,14 +223,16 @@ Figure 2. Working from a local fork to make your changes. upstream https://github.com/open-telemetry/opentelemetry.io.git (push) ``` -1. Fetch commits from your fork's `origin/main` and `open-telemetry/opentelemetry.io`'s `upstream/main`: +1. Fetch commits from your fork's `origin/main` and + `open-telemetry/opentelemetry.io`'s `upstream/main`: ```shell git fetch origin git fetch upstream ``` - This makes sure your local repository is up to date before you start making changes. + This makes sure your local repository is up to date before you start making + changes. #### Create a branch @@ -286,8 +293,8 @@ When you are ready to submit a pull request, commit your changes. #### Preview your changes locally {#preview-locally} -Preview your changes locally before pushing them or opening a pull request. -A preview lets you catch build errors or markdown formatting problems. +Preview your changes locally before pushing them or opening a pull request. A +preview lets you catch build errors or markdown formatting problems. To build and serve the site locally with Hugo, run the following command: @@ -307,7 +314,7 @@ Figure 3 shows the steps to open a PR from your fork to the [open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) . -{{< mermaid >}} +```mermaid flowchart LR subgraph first[ ] direction TB @@ -328,12 +335,14 @@ classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-si classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold class 1,2,3,4,5,6,7,8 grey class first,second white -{{}} +``` Figure 3. Steps to open a PR from your fork to the [open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). -1. In a web browser, go to the [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) repository. +1. In a web browser, go to the + [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) + repository. 1. Select **New Pull Request**. 1. Select **compare across forks**. 1. From the **head repository** drop-down menu, select your fork. @@ -341,32 +350,35 @@ Figure 3. Steps to open a PR from your fork to the 1. Select **Create Pull Request**. 1. Add a description for your pull request: - - **Title** (50 characters or less): Summarize the intent of the change. - - **Description**: Describe the change in more detail. + - **Title** (50 characters or less): Summarize the intent of the change. + - **Description**: Describe the change in more detail. - - If there is a related GitHub issue, include `Fixes #12345` or `Closes #12345` in the - description. GitHub's automation closes the mentioned issue after merging the PR if used. - If there are other related PRs, link those as well. - - If you want advice on something specific, include any questions you'd like reviewers to - think about in your description. + - If there is a related GitHub issue, include `Fixes #12345` or + `Closes #12345` in the description. GitHub's automation closes the + mentioned issue after merging the PR if used. If there are other related + PRs, link those as well. + - If you want advice on something specific, include any questions you'd + like reviewers to think about in your description. 1. Select the **Create pull request** button. Your pull request is available in [Pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls). -After opening a PR, GitHub runs automated tests and tries to deploy a preview using -[Netlify](https://www.netlify.com/). +After opening a PR, GitHub runs automated tests and tries to deploy a preview +using [Netlify](https://www.netlify.com/). - If the Netlify build fails, select **Details** for more information. -- If the Netlify build succeeds, select **Details** opens a staged version of the OpenTelemetry - website with your changes applied. This is how reviewers check your changes. +- If the Netlify build succeeds, select **Details** opens a staged version of + the OpenTelemetry website with your changes applied. This is how reviewers + check your changes. GitHub also automatically assigns labels to a PR to help reviewers. #### Changes from reviewers -Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits. +Sometimes reviewers commit to your pull request. Before making any other +changes, fetch those commits. 1. Fetch commits from your remote fork and rebase your working branch: @@ -399,7 +411,8 @@ create a merge conflict. You must resolve all merge conflicts in your PR. git push --force-with-lease origin ``` -1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and rebase your branch: +1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and + rebase your branch: ```shell git fetch upstream @@ -414,11 +427,11 @@ create a merge conflict. You must resolve all merge conflicts in your PR. This results in a number of files marked as conflicted. -1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. - Resolve the conflict and delete the conflict marker. +1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, + and `===`. Resolve the conflict and delete the conflict marker. - {{< note >}} - For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). + {{< note >}} For more information, see + [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). {{< /note >}} 1. Add the files to the changeset: @@ -435,7 +448,8 @@ create a merge conflict. You must resolve all merge conflicts in your PR. 1. Repeat steps 2 to 5 as needed. - After applying all commits, the `git status` command shows that the rebase is complete. + After applying all commits, the `git status` command shows that the rebase is + complete. 1. Force-push the branch to your fork: @@ -465,12 +479,13 @@ the templates with as much detail as possible when you file issues or PRs. ## Open an issue -If you want to suggest improvements to existing content or notice an error, -open an issue. +If you want to suggest improvements to existing content or notice an error, open +an issue. -1. Click the **Create documentation issue** link on the right sidebar. This redirects you - to a GitHub issue page prepopulated with some headers. -2. Describe the issue or suggestion for improvement. Provide as many details as you can. +1. Click the **Create documentation issue** link on the right sidebar. This + redirects you to a GitHub issue page prepopulated with some headers. +2. Describe the issue or suggestion for improvement. Provide as many details as + you can. 3. Click **Submit new issue**. After submitting, check in on your issue occasionally or turn on GitHub @@ -479,36 +494,37 @@ they can take action on your issue. ### Suggesting new content -If you have an idea for new content, but you aren't sure where it should go, -you can still file an issue. Either: +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/open-telemetry/opentelemetry.io/issues/new/) and file the issue directly. +- Choose an existing page in the section you think the content belongs in and + click **Create documentation issue**. +- Go to [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) + and file the issue directly. ## How to file great issues Keep the following in mind when filing an issue: -- Provide a clear issue description. Describe what specifically is missing, out of date, - wrong, or needs improvement. +- Provide a clear issue description. Describe what specifically is missing, out + of date, wrong, or needs improvement. - Explain the specific impact the issue has on users. - Limit the scope of a given issue to a reasonable unit of work. For problems - with a large scope, break them down into smaller issues. For example, "Fix the security docs" - is too broad, but "Add details to the 'Restricting network access' topic" is specific enough - to be actionable. -- Search the existing issues to see if there's anything related or similar to the - new issue. -- If the new issue relates to another issue or pull request, refer to it - either by its full URL or by the issue or pull request number prefixed - with a `#` character. For example, `Introduced by #987654`. -- Follow the [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). Respect your -fellow contributors. For example, "The docs are terrible" is not + with a large scope, break them down into smaller issues. For example, "Fix the + security docs" is too broad, but "Add details to the 'Restricting network + access' topic" is specific enough to be actionable. +- Search the existing issues to see if there's anything related or similar to + the new issue. +- If the new issue relates to another issue or pull request, refer to it either + by its full URL or by the issue or pull request number prefixed with a `#` + character. For example, `Introduced by #987654`. +- Follow the + [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). + Respect your fellow contributors. For example, "The docs are terrible" is not helpful or polite feedback. - ## Other ways to contribute - Visit the [OpenTelemetry community site](/community/). - Add your application to the [Registry](/ecosystem). - Submit a [blog post or case study](/docs/contribute/blogs-case-studies/). - diff --git a/content/en/docs/Contribute/blogs-case-studies.md b/content/en/docs/Contribute/blogs-case-studies.md index 7c855689b959..f05cb6fa1749 100644 --- a/content/en/docs/Contribute/blogs-case-studies.md +++ b/content/en/docs/Contribute/blogs-case-studies.md @@ -31,50 +31,54 @@ Unsuitable content includes: To submit a blog post, follow these steps: -1. [Sign the CLA](https://docs.linuxfoundation.org/lfx/easycla/contributors) - if you have not yet done so. +1. [Sign the CLA](https://docs.linuxfoundation.org/lfx/easycla/contributors) if + you have not yet done so. 1. Have a look at the Markdown format for existing blog posts in the [opentelemetry.io repository](https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/blog). 1. Write out your blog post in a text editor of your choice. -1. On the same link from step 2, select **Create new file**. Paste your content into the editor. - Name the file to match the proposed title of the blog post, but don’t put the date in the file name. - The blog reviewers will work with you on the final file name and the date the blog will be published. +1. On the same link from step 2, select **Create new file**. Paste your content + into the editor. Name the file to match the proposed title of the blog post, + but don’t put the date in the file name. The blog reviewers will work with + you on the final file name and the date the blog will be published. -1. When you save the file, GitHub will walk you through the pull request process. +1. When you save the file, GitHub will walk you through the pull request + process. -1. A blog post reviewer will review your submission and work with you on feedback and final details. - When the blog post is approved, the blog will be scheduled for publication. +1. A blog post reviewer will review your submission and work with you on + feedback and final details. When the blog post is approved, the blog will be + scheduled for publication. ## Guidelines and expectations -- Blog posts should not be vendor pitches. +- Blog posts should not be vendor pitches. - - Articles must contain content that applies broadly to the OpenTelemetry community. For example, a - submission should focus on upstream OpenTelemetry as opposed to vendor-specific configurations. - Check the [Documentation style guide](/docs/contribute/style/content-guide/#what-s-allowed) for - what is typically allowed on OpenTelemetry properties. - - Links should primarily be to the official OpenTelemetry documentation. When using external - references, links should be diverse - For example a submission shouldn't contain only links - back to a single company's blog. + - Articles must contain content that applies broadly to the OpenTelemetry + community. For example, a submission should focus on upstream OpenTelemetry + as opposed to vendor-specific configurations. + - Links should primarily be to the official OpenTelemetry documentation. When + using external references, links should be diverse - For example a + submission shouldn't contain only links back to a single company's blog. - Blog posts are not published on specific dates. - - Articles are reviewed by community volunteers. We'll try our best to accommodate specific - timing, but we make no guarantees. - - Many core parts of the OpenTelemetry projects submit blog posts during release windows, delaying - publication times. Consider submitting during a quieter period of the release cycle. - - If you are looking for greater coordination on post release dates, coordinating with - [CNCF marketing](https://www.cncf.io/about/contact/) is a more appropriate choice than submitting a blog post. + - Articles are reviewed by community volunteers. We'll try our best to + accommodate specific timing, but we make no guarantees. + - Many core parts of the OpenTelemetry projects submit blog posts during + release windows, delaying publication times. Consider submitting during a + quieter period of the release cycle. + - If you are looking for greater coordination on post release dates, + coordinating with [CNCF marketing](https://www.cncf.io/about/contact/) is a + more appropriate choice than submitting a blog post. - Blog posts should be relevant to OpenTelemetry users. - - Topics related to participation in or results of OpenTelemetry SIGs activities are always on - topic. - - Posts about other CNCF projects may or may not be on topic. We recommend asking the blog team - before submitting a draft. - - Many CNCF projects have their own blog. These are often a better choice for posts. There are - times of major feature or milestone for a CNCF project that users would be interested in - reading on the OpenTelemetry blog. + - Topics related to participation in or results of OpenTelemetry SIGs + activities are always on topic. + - Posts about other CNCF projects may or may not be on topic. We recommend + asking the blog team before submitting a draft. + - Many CNCF projects have their own blog. These are often a better choice for + posts. There are times of major feature or milestone for a CNCF project that + users would be interested in reading on the OpenTelemetry blog. diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index c6b0adf7bbb6..5379b6c2e3d1 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -6,669 +6,22 @@ cSpell:ignore: slug: style-guide --- -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 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 -or addition, [add it to the agenda](https://bit.ly/sig-docs-agenda) for an upcoming -SIG Docs meeting, and attend the meeting to participate in the discussion. - - - -{{< note >}} -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 -glossary entries, tabs, and representing feature state. -{{< /note >}} - -## Language - -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 OpenTelemetry Documentation](/docs/contribute/localization/). - -The English-language documentation uses U.S. English spelling and grammar. - -{{< comment >}}[If you're localizing this page, you can omit the point about US English.]{{< /comment >}} - -## Documentation formatting standards - -### Use upper camel case for API objects - -When you refer specifically to interacting with an API object, use -[UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), also known as -Pascal case. You may see different capitalization, such as "configMap", -in the [API Reference](/docs/reference/kubernetes-api/). When writing -general documentation, it's better to use upper camel case, calling it "ConfigMap" instead. - -When you are generally discussing an API object, use -[sentence-style capitalization](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization). - -The following examples focus on capitalization. For more information about formatting -API object names, review the related guidance on [Code Style](#code-style-inline-code). - -{{< table caption = "Do and Don't - Use Pascal case for API objects" >}} -Do | Don't -:--| :----- -The HorizontalPodAutoscaler resource is responsible for ... | The Horizontal pod autoscaler is responsible for ... -A PodList object is a list of pods. | A Pod List object is a list of pods. -The Volume object contains a `hostPath` field. | The volume object contains a hostPath field. -Every ConfigMap object is part of a namespace. | Every configMap object is part of a namespace. -For managing confidential data, consider using the Secret API. | For managing confidential data, consider using the secret API. -{{< /table >}} - -### Use angle brackets for placeholders - -Use angle brackets for placeholders. Tell the reader what a placeholder -represents, for example: - -Display information about a pod: - -```shell -kubectl describe pod -n -``` - -If the namespace of the pod is `default`, you can omit the '-n' parameter. - -### Use bold for user interface elements - -{{< table caption = "Do and Don't - Bold interface elements" >}} -Do | Don't -:--| :----- -Click **Fork**. | Click "Fork". -Select **Other**. | Select "Other". -{{< /table >}} - -### Use italics to define or introduce new terms - -{{< table caption = "Do and Don't - Use italics for new terms" >}} -Do | Don't -:--| :----- -A _cluster_ is a set of nodes ... | A "cluster" is a set of nodes ... -These components form the _control plane_. | These components form the **control plane**. -{{< /table >}} - -### Use code style for filenames, directories, and paths - -{{< table caption = "Do and Don't - Use code style for filenames, directories, and paths" >}} -Do | Don't -:--| :----- -Open the `envars.yaml` file. | Open the envars.yaml file. -Go to the `/docs/tutorials` directory. | Go to the /docs/tutorials directory. -Open the `/_data/concepts.yaml` file. | Open the /\_data/concepts.yaml file. -{{< /table >}} - -### Use the international standard for punctuation inside quotes - -{{< table caption = "Do and Don't - Use the international standard for punctuation inside quotes" >}} -Do | Don't -:--| :----- -events are recorded with an associated "stage". | events are recorded with an associated "stage." -The copy is called a "fork". | The copy is called a "fork." -{{< /table >}} - -## Inline code formatting - -### Use code style for inline code, commands, and API objects {#code-style-inline-code} - -For inline code in an HTML document, use the `` tag. In a Markdown -document, use the backtick (`` ` ``). - -{{< table caption = "Do and Don't - Use code style for inline code, commands, and API objects" >}} -Do | Don't -:--| :----- -The `kubectl run` command creates a `Pod`. | The "kubectl run" command creates a pod. -The kubelet on each node acquires a `Lease`… | The kubelet on each node acquires a lease… -A `PersistentVolume` represents durable storage… | A Persistent Volume represents durable storage… -For declarative management, use `kubectl apply`. | For declarative management, use "kubectl apply". -Enclose code samples with triple backticks. (\`\`\`)| Enclose code samples with any other syntax. -Use single backticks to enclose inline code. For example, `var example = true`. | Use two asterisks (`**`) or an underscore (`_`) to enclose inline code. For example, **var example = true**. -Use triple backticks before and after a multi-line block of code for fenced code blocks. | Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations. -Use meaningful variable names that have a context. | Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context. -Remove trailing spaces in the code. | Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well. -{{< /table >}} - -{{< note >}} -The website supports syntax highlighting for code samples, but specifying a language -is optional. Syntax highlighting in the code block should conform to the -[contrast guidelines.](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0&showtechniques=141%2C143#contrast-minimum) -{{< /note >}} - -### Use code style for object field names and namespaces - -{{< table caption = "Do and Don't - Use code style for object field names" >}} -Do | Don't -:--| :----- -Set the value of the `replicas` field in the configuration file. | Set the value of the "replicas" field in the configuration file. -The value of the `exec` field is an ExecAction object. | The value of the "exec" field is an ExecAction object. -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 OpenTelemetry 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. -The `kubectl` handles locating and authenticating to the API server. | The kubectl handles locating and authenticating to the apiserver. -Run the process with the certificate, `kube-apiserver --client-ca-file=FILENAME`. | Run the process with the certificate, kube-apiserver --client-ca-file=FILENAME. | -{{< /table >}} - -### Starting a sentence with a component tool or component name - -{{< table caption = "Do and Don't - Starting a sentence with a component tool or component name" >}} -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 OpenTelemetry. | kube-scheduler is the default scheduler for OpenTelemetry. -{{< /table >}} - -### Use a general descriptor over a component name - -{{< table caption = "Do and Don't - Use a general descriptor over a component name" >}} -Do | Don't -:--| :----- -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 >}} - -### Use normal style for string and integer field values - -For field values of type string or integer, use normal style without quotation marks. - -{{< table caption = "Do and Don't - Use normal style for string and integer field values" >}} -Do | Don't -:--| :----- -Set the value of `imagePullPolicy` to Always. | Set the value of `imagePullPolicy` to "Always". -Set the value of `image` to nginx:1.16. | Set the value of `image` to `nginx:1.16`. -Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`. -{{< /table >}} - -## Referring to OpenTelemetry API resources - -This section talks about how we reference API resources in the documentation. - -### Clarification about "resource" - -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 OpenTelemetry API terminologies - -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 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`". - -### API resource names - -Always format API resource names using [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), -also known as PascalCase, and code formatting. - -For inline code in an HTML document, use the `` tag. In a Markdown document, use the backtick (`` ` ``). - -Don't split an API object name into separate words. For example, use `PodTemplateList`, not Pod Template List. - -For more information about PascalCase and code formatting, please review the related guidance on -[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 OpenTelemetry API terminologies, please review the related -guidance on [OpenTelemetry API terminology](/docs/reference/using-api/api-concepts/#standard-api-terminology). - -## Code snippet formatting - -### Don't include the command prompt - -{{< table caption = "Do and Don't - Don't include the command prompt" >}} -Do | Don't -:--| :----- -kubectl get pods | $ kubectl get pods -{{< /table >}} - -### Separate commands from output - -Verify that the pod is running on your chosen node: - -```shell -kubectl get pods --output=wide -``` - -The output is similar to this: - -```console -NAME READY STATUS RESTARTS AGE IP NODE -nginx 1/1 Running 0 13s 10.200.0.4 worker0 -``` - -### 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 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 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 OpenTelemetry version 1.8, -the front-matter of your markdown file should look something like: - -```yaml ---- -title: -min-kubernetes-server-version: v1.8 ---- -``` - -In code and configuration examples, do not include comments about alternative versions. -Be careful to not include incorrect statements in your examples as comments, such as: - -```yaml -apiVersion: v1 # earlier versions use... -kind: Pod -... -``` +The OpenTelemetry documentation adheres to the +[Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) +and the +[Google Developer Documentation Style Guide](https://developers.google.com/style) +. The following sections contain guidance that is specific to the OpenTelemetry +project. ## OpenTelemetry.io word list -A list of OpenTelemetry-specific terms and words to be used consistently across the site. - -{{< table caption = "OpenTelemetry.io word list" >}} -Term | Usage -:--- | :---- -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. -{{< /table >}} - -## Shortcodes - -Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create -different rhetorical appeal levels. Our documentation supports three different -shortcodes in this category: **Note** `{{}}`, -**Caution** `{{}}`, and **Warning** `{{}}`. - -1. Surround the text with an opening and closing shortcode. - -2. Use the following syntax to apply a style: - - ```none - {{}} - No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.) - {{}} - ``` - - The output is: - - {{< note >}} - The prefix you choose is the same text for the tag. - {{< /note >}} - -### Note - -Use `{{}}` to highlight a tip or a piece of information that may be helpful to know. - -For example: - -``` -{{}} -You can _still_ use Markdown inside these callouts. -{{}} -``` - -The output is: - -{{< note >}} -You can _still_ use Markdown inside these callouts. -{{< /note >}} - -You can use a `{{}}` in a list: - -``` -1. Use the note shortcode in a list - -1. A second item with an embedded note - - {{}} - Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues). - {{}} - -1. A third item in a list - -1. A fourth item in a list -``` - -The output is: - -1. Use the note shortcode in a list - -1. A second item with an embedded note - - {{< note >}} - Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues). - {{< /note >}} - -1. A third item in a list - -1. A fourth item in a list - -### Caution - -Use `{{}}` to call attention to an important piece of information to avoid pitfalls. - -For example: - -``` -{{}} -The callout style only applies to the line directly above the tag. -{{}} -``` - -The output is: - -{{< caution >}} -The callout style only applies to the line directly above the tag. -{{< /caution >}} - -### Warning - -Use `{{}}` to indicate danger or a piece of information that is crucial to follow. - -For example: - -``` -{{}} -Beware. -{{}} -``` - -The output is: - -{{< warning >}} -Beware. -{{< /warning >}} - -## Common Shortcode Issues - -### Ordered Lists - -Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag. - -For example: - - 1. Preheat oven to 350˚F - - 1. Prepare the batter, and pour into springform pan. - {{}}Grease the pan for best results.{{}} - - 1. Bake for 20-25 minutes or until set. - -The output is: - -1. Preheat oven to 350˚F - -1. Prepare the batter, and pour into springform pan. - - {{< note >}}Grease the pan for best results.{{< /note >}} - -1. Bake for 20-25 minutes or until set. - -### Include Statements - -Shortcodes inside include statements will break the build. You must insert them -in the parent document, before and after you call the include. For example: - -``` -{{}} -{{}} -{{}} -``` - -## Markdown elements - -### Line breaks - -Use a single newline to separate block-level content like headings, lists, images, -code blocks, and others. The exception is second-level headings, where it should -be two newlines. Second-level headings follow the first-level (or the title) without -any preceding paragraphs or texts. A two line spacing helps visualize the overall -structure of content in a code editor better. - -Manually wrap paragraphs in the Markdown source when appropriate. Since the git -tool and the GitHub website generate file diffs on a line-by-line basis, -manually wrapping long lines helps the reviewers to easily find out the changes -made in a PR and provide feedback. It also helps the downstream localization -teams where people track the upstream changes on a per-line basis. Line -wrapping can happen at the end of a sentence or a punctuation character, for -example. One exception to this is that a Markdown link or a shortcode is -expected to be in a single line. - -### Headings and titles {#headings} - -People accessing this documentation may use a screen reader or other assistive technology (AT). -[Screen readers](https://en.wikipedia.org/wiki/Screen_reader) are linear output devices, -they output items on a page one at a time. If there is a lot of content on a page, you can -use headings to give the page an internal structure. A good page structure helps all readers -to easily navigate the page or filter topics of interest. - -{{< table caption = "Do and Don't - Headings" >}} -Do | Don't -:--| :----- -Update the title in the front matter of the page or blog post. | Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading. -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: 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 - -{{< table caption = "Do and Don't - Paragraphs" >}} -Do | Don't -:--| :----- -Try to keep paragraphs under 6 sentences. | Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it. -Use three hyphens (`---`) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section. | Use horizontal rules for decoration. -{{< /table >}} - -### Links - -{{< table caption = "Do and Don't - Links" >}} -Do | Don't -:--| :----- -Write hyperlinks that give you context for the content they link to. For example: Certain ports are open on your machines. See Check required ports for more details. | Use ambiguous terms such as "click here". For example: Certain ports are open on your machines. See here for more details. -Write Markdown-style links: `[link text](URL)`. For example: `[Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions)` and the output is [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions). | Write HTML-style links: `Visit our tutorial!`, or create links that open in new tabs or windows. For example: `[example website](https://example.com){target="_blank"}` -{{< /table >}} - -### Lists - -Group items in a list that are related to each other and need to appear in a specific -order or to indicate a correlation between multiple items. When a screen reader comes -across a list—whether it is an ordered or unordered list—it will be announced to the -user that there is a group of list items. The user can then use the arrow keys to move -up and down between the various items in the list. Website navigation links can also be -marked up as list items; after all they are nothing but a group of related links. - -- End each item in a list with a period if one or more items in the list are complete - sentences. For the sake of consistency, normally either all items or none should be complete sentences. - - {{< note >}} - Ordered lists that are part of an incomplete introductory sentence can be in lowercase - and punctuated as if each item was a part of the introductory sentence. - {{< /note >}} - -- Use the number one (`1.`) for ordered lists. - -- Use (`+`), (`*`), or (`-`) for unordered lists. - -- Leave a blank line after each list. - -- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅). - -- List items may consist of multiple paragraphs. Each subsequent paragraph in a list - item must be indented by either four spaces or one tab. - -### Tables - -The semantic purpose of a data table is to present tabular data. Sighted users can -quickly scan the table but a screen reader goes through line by line. A table caption -is used to create a descriptive title for a data table. Assistive technologies (AT) -use the HTML table caption element to identify the table contents to the user within the page structure. - -- Add table captions using [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions) for tables. - -## Content best practices - -This section contains suggested best practices for clear, concise, and consistent content. - -### Use present tense - -{{< table caption = "Do and Don't - Use present tense" >}} -Do | Don't -:--| :----- -This command starts a proxy. | This command will start a proxy. - {{< /table >}} - -Exception: Use future or past tense if it is required to convey the correct -meaning. - -### Use active voice - -{{< table caption = "Do and Don't - Use active voice" >}} -Do | Don't -:--| :----- -You can explore the API using a browser. | The API can be explored using a browser. -The YAML file specifies the replica count. | The replica count is specified in the YAML file. -{{< /table >}} - -Exception: Use passive voice if active voice leads to an awkward construction. - -### Use simple and direct language - -Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." - -{{< table caption = "Do and Don't - Use simple and direct language" >}} -Do | Don't -:--| :----- -To create a ReplicaSet, ... | In order to create a ReplicaSet, ... -See the configuration file. | Please see the configuration file. -View the pods. | With this next command, we'll view the pods. -{{< /table >}} - -### Address the reader as "you" - -{{< table caption = "Do and Don't - Addressing the reader" >}} -Do | Don't -:--| :----- -You can create a Deployment by ... | We'll create a Deployment by ... -In the preceding output, you can see... | In the preceding output, we can see ... -{{< /table >}} - -### Avoid Latin phrases - -Prefer English terms over Latin abbreviations. - -{{< table caption = "Do and Don't - Avoid Latin phrases" >}} -Do | Don't -:--| :----- -For example, ... | e.g., ... -That is, ...| i.e., ... -{{< /table >}} - -Exception: Use "etc." for et cetera. - -## Patterns to avoid - -### Avoid using "we" - -Using "we" in a sentence can be confusing, because the reader might not know -whether they're part of the "we" you're describing. - -{{< table caption = "Do and Don't - Patterns to avoid" >}} -Do | Don't -:--| :----- -Version 1.4 includes ... | In version 1.4, we have added ... -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 >}} - -### Avoid jargon and idioms - -Some readers speak English as a second language. Avoid jargon and idioms to help them understand better. - -{{< table caption = "Do and Don't - Avoid jargon and idioms" >}} -Do | Don't -:--| :----- -Internally, ... | Under the hood, ... -Create a new cluster. | Turn up a new cluster. -{{< /table >}} - -### Avoid statements about the future - -Avoid making promises or giving hints about the future. If you need to talk about -an alpha feature, put the text under a heading that identifies it as alpha -information. - -An exception to this rule is documentation about announced deprecations -targeting removal in future versions. One example of documentation like this -is the [Deprecated API migration guide](/docs/reference/using-api/deprecation-guide/). - -### Avoid statements that will soon be out of date - -Avoid words like "currently" and "new." A feature that is new today might not be -considered new in a few months. - -{{< table caption = "Do and Don't - Avoid statements that will soon be out of date" >}} -Do | Don't -:--| :----- -In version 1.4, ... | In the current version, ... -The Federation feature provides ... | The new Federation feature provides ... -{{< /table >}} - -### Avoid words that assume a specific level of understanding - -Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value. - -{{< table caption = "Do and Don't - Avoid insensitive words" >}} -Do | Don't -:--| :----- -Include one command in ... | Include just one command in ... -Run the container ... | Simply run the container ... -You can remove ... | You can easily remove ... -These steps ... | These simple steps ... -{{< /table >}} - -### EditorConfig file -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/open-telemetry/opentelemetry.io/blob/main/.editorconfig) in the repository root. - -## {{% heading "whatsnext" %}} +A list of OpenTelemetry-specific terms and words to be used consistently across +the site. -* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/). -* Learn about [using page templates](/docs/contribute/style/page-content-types/). -* Learn about [custom hugo shortcodes](/docs/contribute/style/hugo-shortcodes/). -* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/). + +| Term | Usage | +| --- | --- | +| OpenTelemetry | OpenTelemetry should always be capitalized. | +| OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. | +| Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. | + From d7094aaece537fafd998c57c90037bc352e5f8c2 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Mon, 11 Dec 2023 17:27:27 +0100 Subject: [PATCH 31/62] More fixes --- content/en/docs/Contribute/style-guide.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index 5379b6c2e3d1..2787a68ad822 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -25,3 +25,6 @@ the site. | OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. | | Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. | + +See also the [Glossary](/docs/concepts/glossary/) for a list of OpenTelemetry +terms and their definition. \ No newline at end of file From f1e63e1209d4d40f75f4b03e0abe669618e0febc Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 12 Dec 2023 10:00:08 +0100 Subject: [PATCH 32/62] Fix linter issues --- content/en/docs/Contribute/_index.md | 30 ++++++------- .../en/docs/Contribute/blogs-case-studies.md | 4 +- content/en/docs/Contribute/style-guide.md | 9 ++-- static/refcache.json | 44 +++++++++++++++++++ 4 files changed, 65 insertions(+), 22 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 8ccc13bbf113..abe159372a8d 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -2,12 +2,12 @@ title: Contribute description: Learn how to contribute to the OpenTelemetry documentation. weight: 200 -cSpell:ignore: +cSpell:ignore: spacewhite prepopulated linktitle open-telemetry repos --- You can open an issue about OpenTelemetry documentation, or contribute a change with a pull request (PR) to the -[`open-telemetry/opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). +[`opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io). OpenTelemetry documentation contributors: @@ -25,8 +25,8 @@ Conduct. To contribute, you need to be familiar with the following techs and tools: -- [git](https://git-scm.com/) -- [GitHub](https://lab.github.com/) +- git +- GitHub - Markdown (CommonMark) - YAML @@ -184,10 +184,10 @@ class changes,changes2 white Figure 2. Working from a local fork to make your changes. -#### Fork the open-telemetry/opentelemetry.io repository +#### Fork the opentelemetry.io repository 1. Navigate to the - [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) + [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/) repository. 1. Select **Fork**. @@ -311,14 +311,13 @@ close the terminal window. #### Open a pull request from your fork {#open-a-pr} Figure 3 shows the steps to open a PR from your fork to the -[open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) -. +[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) . ```mermaid flowchart LR subgraph first[ ] direction TB -1[1. Go to open-telemetry/opentelemetry.io repository] --> 2[2. Select New Pull Request] +1[1. Go to opentelemetry.io repository] --> 2[2. Select New Pull Request] 2 --> 3[3. Select compare across forks] 3 --> 4[4. Select your fork from
head repository drop-down menu] end @@ -338,10 +337,10 @@ class first,second white ``` Figure 3. Steps to open a PR from your fork to the -[open-telemetry/opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). +[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io). 1. In a web browser, go to the - [`open-telemetry/opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) + [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io) repository. 1. Select **New Pull Request**. 1. Select **compare across forks**. @@ -430,9 +429,8 @@ create a merge conflict. You must resolve all merge conflicts in your PR. 1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`, and `===`. Resolve the conflict and delete the conflict marker. - {{< note >}} For more information, see + For more information, see [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented). - {{< /note >}} 1. Add the files to the changeset: @@ -461,9 +459,9 @@ create a merge conflict. You must resolve all merge conflicts in your PR. ## Contribute to other repos -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. +The OpenTelemetry project contains many repositories. Many of these repositories +contain documentation: user-facing help text, error messages, API references or +code comments. If you see text you'd like to improve, use GitHub to search all repositories in the OpenTelemetry organization. This can help you figure out where to submit diff --git a/content/en/docs/Contribute/blogs-case-studies.md b/content/en/docs/Contribute/blogs-case-studies.md index f05cb6fa1749..5f08e2456ac7 100644 --- a/content/en/docs/Contribute/blogs-case-studies.md +++ b/content/en/docs/Contribute/blogs-case-studies.md @@ -1,9 +1,9 @@ --- title: Submit a blog post -linktitle: Submit a blog post +linkTitle: Submit a blog post slug: blogs-case-studies weight: 30 -cSpell:ignore: +cSpell:ignore: open-telemetry --- The [OpenTelemetry blog](/blog/) communicates new features, community reports, diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index 2787a68ad822..1756d819705a 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -1,9 +1,9 @@ --- title: Documentation style guide -linktitle: Style guide +linkTitle: Style guide weight: 40 cSpell:ignore: -slug: style-guide +slug: style-guide open-telemetry --- The OpenTelemetry documentation adheres to the @@ -21,10 +21,11 @@ the site. | Term | Usage | | --- | --- | -| OpenTelemetry | OpenTelemetry should always be capitalized. | +| OpenTelemetry | OpenTelemetry should always be capitalized. Don't use Open-Telemetry. | | OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. | | Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. | +| Repository | Code repositories. Don't use repo or repos. | See also the [Glossary](/docs/concepts/glossary/) for a list of OpenTelemetry -terms and their definition. \ No newline at end of file +terms and their definition. diff --git a/static/refcache.json b/static/refcache.json index 1909ff429c64..db86be8aa726 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -739,6 +739,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T15:51:20.598962-04:00" }, + "https://developers.google.com/style": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:04:54.694842+01:00" + }, "https://devstats.cncf.io/": { "StatusCode": 206, "LastSeen": "2023-06-29T16:21:23.471592-04:00" @@ -1107,6 +1111,10 @@ "StatusCode": 206, "LastSeen": "2023-09-15T16:58:35.759747+02:00" }, + "https://docs.linuxfoundation.org/lfx/easycla/contributors": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:05:05.806034+01:00" + }, "https://docs.locust.io/en/stable/writing-a-locustfile.html": { "StatusCode": 200, "LastSeen": "2023-06-29T15:47:17.793642-04:00" @@ -1959,6 +1967,18 @@ "StatusCode": 200, "LastSeen": "2023-06-29T16:04:43.002783-04:00" }, + "https://git-scm.com/": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:04:54.723883+01:00" + }, + "https://git-scm.com/book/en/v2/Getting-Started-Installing-Git": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:05.965228+01:00" + }, + "https://git-scm.com/docs/git-merge#_how_conflicts_are_presented": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:07.954292+01:00" + }, "https://github.blog/2021-05-26-why-and-how-github-is-adopting-opentelemetry/": { "StatusCode": 200, "LastSeen": "2023-06-30T16:26:22.927158-04:00" @@ -3687,6 +3707,10 @@ "StatusCode": 200, "LastSeen": "2023-06-30T08:48:34.579016-04:00" }, + "https://github.com/open-telemetry/opentelemetry.io": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:04:54.562763+01:00" + }, "https://github.com/open-telemetry/opentelemetry.io#adding-a-project-to-the-opentelemetry-registry": { "StatusCode": 200, "LastSeen": "2023-06-30T08:46:35.260059-04:00" @@ -3699,6 +3723,10 @@ "StatusCode": 200, "LastSeen": "2023-09-08T10:57:01.381266-04:00" }, + "https://github.com/open-telemetry/opentelemetry.io/": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:06.564186+01:00" + }, "https://github.com/open-telemetry/opentelemetry.io/issues/new": { "StatusCode": 200, "LastSeen": "2023-06-30T08:31:06.342368-04:00" @@ -3715,6 +3743,10 @@ "StatusCode": 200, "LastSeen": "2023-09-12T11:57:04.702626-04:00" }, + "https://github.com/open-telemetry/opentelemetry.io/pulls": { + "StatusCode": 200, + "LastSeen": "2023-12-12T09:05:07.270135+01:00" + }, "https://github.com/open-telemetry/otel-arrow": { "StatusCode": 200, "LastSeen": "2023-11-14T11:45:08.675719+01:00" @@ -4527,6 +4559,10 @@ "StatusCode": 206, "LastSeen": "2023-07-28T12:17:39.145108-04:00" }, + "https://kubernetes.io/docs/contribute/style/style-guide/": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:04:54.259484+01:00" + }, "https://kubernetes.io/docs/reference/kubectl/": { "StatusCode": 206, "LastSeen": "2023-06-30T11:49:31.853471-04:00" @@ -6127,6 +6163,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T18:48:57.135457-04:00" }, + "https://www.cncf.io/about/contact/": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:05:06.564168+01:00" + }, "https://www.cncf.io/blog/2019/05/21/a-brief-history-of-opentelemetry-so-far/": { "StatusCode": 206, "LastSeen": "2023-06-30T09:22:37.957195-04:00" @@ -6507,6 +6547,10 @@ "StatusCode": 206, "LastSeen": "2023-10-16T20:09:59.62173+02:00" }, + "https://www.netlify.com/": { + "StatusCode": 206, + "LastSeen": "2023-12-12T09:05:07.468279+01:00" + }, "https://www.nomadproject.io": { "StatusCode": 206, "LastSeen": "2023-06-30T08:50:51.721695-04:00" From 8cecc7cd9eb246ba8d5b8ebefbbafca15368434b Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 12 Dec 2023 10:04:06 +0100 Subject: [PATCH 33/62] Fix terminology error --- content/en/docs/Contribute/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index abe159372a8d..f60b465ce730 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -457,7 +457,7 @@ create a merge conflict. You must resolve all merge conflicts in your PR. The pull request no longer shows any conflicts. -## Contribute to other repos +## Contribute to other repositories The OpenTelemetry project contains many repositories. Many of these repositories contain documentation: user-facing help text, error messages, API references or From 8c7d12da8f53c01c3a14412f66083a00a7f7704f Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 12 Dec 2023 10:06:05 +0100 Subject: [PATCH 34/62] Linter fixes --- content/en/docs/Contribute/_index.md | 2 +- content/en/docs/Contribute/style-guide.md | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index f60b465ce730..8fb53c3b0177 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -2,7 +2,7 @@ title: Contribute description: Learn how to contribute to the OpenTelemetry documentation. weight: 200 -cSpell:ignore: spacewhite prepopulated linktitle open-telemetry repos +cSpell:ignore: linktitle open-telemetry prepopulated repos spacewhite --- You can open an issue about OpenTelemetry documentation, or contribute a change diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/Contribute/style-guide.md index 1756d819705a..11b68aafea15 100644 --- a/content/en/docs/Contribute/style-guide.md +++ b/content/en/docs/Contribute/style-guide.md @@ -2,7 +2,6 @@ title: Documentation style guide linkTitle: Style guide weight: 40 -cSpell:ignore: slug: style-guide open-telemetry --- From c45b842d930f2b94da04555b7a1cd3eadcc825e7 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:02:26 +0100 Subject: [PATCH 35/62] Update content/en/docs/Contribute/_index.md Co-authored-by: Severin Neumann --- content/en/docs/Contribute/_index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 8fb53c3b0177..b3919f29fc4b 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -132,8 +132,7 @@ Figure 1. Steps for opening a PR using GitHub. 1. Select **Create pull request**. Before merging a pull request, OpenTelemetry community members review and -approve it. If you have someone in mind, leave a comment with their GitHub -username in it. +approve it. If a reviewer asks you to make changes: From fc668d79cfd5c047a0a437674ca3add6c16c8878 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:02:34 +0100 Subject: [PATCH 36/62] Update content/en/docs/Contribute/_index.md Co-authored-by: Severin Neumann --- content/en/docs/Contribute/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index b3919f29fc4b..0e2d58cda37f 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -25,9 +25,9 @@ Conduct. To contribute, you need to be familiar with the following techs and tools: -- git -- GitHub -- Markdown (CommonMark) +- [git](https://git-scm.com/) +- [GitHub](https://github.com/) +- Markdown ([CommonMark](https://commonmark.org/)) - YAML For technical details concerning how the documentation is built and tested From 3f6f2c30da4e48e488091a6787cdc452bba7c2de Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:03:00 +0100 Subject: [PATCH 37/62] Update content/en/docs/Contribute/_index.md Co-authored-by: Severin Neumann --- content/en/docs/Contribute/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 0e2d58cda37f..1c392ae218a7 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -141,7 +141,7 @@ If a reviewer asks you to make changes: 1. Make the changes requested. 1. Commit the changes. -When your review is complete, a reviewer merges your PR and your changes go liv +When your review is complete, a reviewer merges your PR and your changes goes live a few minutes later. ### Work from a local fork {#fork-the-repo} From b6ec84a0d2918aa39410520185645dd15214912e Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:09:18 +0100 Subject: [PATCH 38/62] Edit --- content/en/docs/Contribute/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/Contribute/_index.md index 1c392ae218a7..2117fe3e22df 100644 --- a/content/en/docs/Contribute/_index.md +++ b/content/en/docs/Contribute/_index.md @@ -458,9 +458,9 @@ create a merge conflict. You must resolve all merge conflicts in your PR. ## Contribute to other repositories -The OpenTelemetry project contains many repositories. Many of these repositories -contain documentation: user-facing help text, error messages, API references or -code comments. +The OpenTelemetry project contains many repositories. Several of these +repositories contain documentation: user-facing help text, error messages, API +references or code comments. If you see text you'd like to improve, use GitHub to search all repositories in the OpenTelemetry organization. This can help you figure out where to submit From 8bf2c9cf5549f23e08095a2ba4c92cf58b331bf1 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:14:14 +0100 Subject: [PATCH 39/62] Change casing --- content/en/docs/{Contribute => contribute}/_index.md | 0 content/en/docs/{Contribute => contribute}/acknowledgements.md | 0 content/en/docs/{Contribute => contribute}/blogs-case-studies.md | 0 content/en/docs/{Contribute => contribute}/style-guide.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename content/en/docs/{Contribute => contribute}/_index.md (100%) rename content/en/docs/{Contribute => contribute}/acknowledgements.md (100%) rename content/en/docs/{Contribute => contribute}/blogs-case-studies.md (100%) rename content/en/docs/{Contribute => contribute}/style-guide.md (100%) diff --git a/content/en/docs/Contribute/_index.md b/content/en/docs/contribute/_index.md similarity index 100% rename from content/en/docs/Contribute/_index.md rename to content/en/docs/contribute/_index.md diff --git a/content/en/docs/Contribute/acknowledgements.md b/content/en/docs/contribute/acknowledgements.md similarity index 100% rename from content/en/docs/Contribute/acknowledgements.md rename to content/en/docs/contribute/acknowledgements.md diff --git a/content/en/docs/Contribute/blogs-case-studies.md b/content/en/docs/contribute/blogs-case-studies.md similarity index 100% rename from content/en/docs/Contribute/blogs-case-studies.md rename to content/en/docs/contribute/blogs-case-studies.md diff --git a/content/en/docs/Contribute/style-guide.md b/content/en/docs/contribute/style-guide.md similarity index 100% rename from content/en/docs/Contribute/style-guide.md rename to content/en/docs/contribute/style-guide.md From a147bdbd2eed86833d3288c3461b925ba5de03b8 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 11:48:24 +0100 Subject: [PATCH 40/62] Halfway peer edits --- content/en/docs/contribute/_index.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 2117fe3e22df..0c24220c9228 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -55,9 +55,10 @@ flowchart LR subgraph first[How to contribute] direction TB T[ ] -.- - A[Sign the CNCF CLA] --> D[Write docs in markdown
and build site with Hugo] - D[Write docs in markdown
and build site with Hugo] --- E[Push source to GitHub] - E --- G[Open a pull request] + B[Fork the repo in GitHub] --- C[Write docs in markdown
and build site with Hugo] + C --- D[Push source to the fork] + D --- E[Open a pull request] + E --- F[Sign the CNCF CLA] end classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; @@ -118,6 +119,8 @@ Figure 1. Steps for opening a PR using GitHub. 1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. +1. If you're not a member of the project, GitHub will offer to create a fork of the repository. Select **Fork this repository**. + 1. Make your changes in the GitHub editor. 1. Below the editor, fill in the **Propose file change** form. @@ -138,7 +141,7 @@ If a reviewer asks you to make changes: 1. Go to the **Files changed** tab. 1. Select the pencil (edit) icon on any files changed by the pull request. -1. Make the changes requested. +1. Make the changes requested. If there's a code suggestion, apply it. 1. Commit the changes. When your review is complete, a reviewer merges your PR and your changes goes live @@ -231,7 +234,8 @@ Figure 2. Working from a local fork to make your changes. ``` This makes sure your local repository is up to date before you start making - changes. + changes. Push changes from upstream to origin regularly to keep you fork in + sync with upstream. #### Create a branch @@ -290,6 +294,8 @@ When you are ready to submit a pull request, commit your changes. git push origin ``` +1. Once the changes are pushed, GitHub lets you know that you can create a PR. + #### Preview your changes locally {#preview-locally} Preview your changes locally before pushing them or opening a pull request. A @@ -371,6 +377,13 @@ using [Netlify](https://www.netlify.com/). the OpenTelemetry website with your changes applied. This is how reviewers check your changes. +Other checks might also fail, including: + +- File name checks +- Links resolution +- Markdown formatting +- Spelling + GitHub also automatically assigns labels to a PR to help reviewers. #### Changes from reviewers @@ -391,6 +404,8 @@ changes, fetch those commits. git push --force-with-lease origin ``` +You can also solve merge conflicts from the GitHub UI. + #### Merge conflicts and rebasing If another contributor commits changes to the same file in another PR, it can From 7eb076d4c7f1440c18e2b2fd387e6b6a2f8b7721 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 14:55:32 +0100 Subject: [PATCH 41/62] Further edits --- content/en/docs/contribute/_index.md | 72 +++++++++++++---------- content/en/docs/contribute/style-guide.md | 11 +++- 2 files changed, 50 insertions(+), 33 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 0c24220c9228..6b1a67e38312 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -119,7 +119,8 @@ Figure 1. Steps for opening a PR using GitHub. 1. On the page where you see the issue, select the **Edit this page** option in the right-hand side navigation panel. -1. If you're not a member of the project, GitHub will offer to create a fork of the repository. Select **Fork this repository**. +1. If you're not a member of the project, GitHub will offer to create a fork of + the repository. Select **Fork this repository**. 1. Make your changes in the GitHub editor. @@ -144,8 +145,8 @@ If a reviewer asks you to make changes: 1. Make the changes requested. If there's a code suggestion, apply it. 1. Commit the changes. -When your review is complete, a reviewer merges your PR and your changes goes live -a few minutes later. +When your review is complete, a reviewer merges your PR and your changes goes +live a few minutes later. ### Work from a local fork {#fork-the-repo} @@ -471,48 +472,37 @@ create a merge conflict. You must resolve all merge conflicts in your PR. The pull request no longer shows any conflicts. -## Contribute to other repositories - -The OpenTelemetry project contains many repositories. Several of these -repositories contain documentation: user-facing help text, error messages, API -references or code comments. - -If you see text you'd like to improve, use GitHub to search all repositories in -the OpenTelemetry organization. This can help you figure out where to submit -your issue or PR. - -Each repository has its own processes and procedures. Before you file an issue -or submit a PR, read that repository's `README.md`, `CONTRIBUTING.md`, and -`code-of-conduct.md`, if they exist. - -Most repositories use issue and PR templates. Have a look through some open -issues and PRs to get a feel for that team's processes. Make sure to fill out -the templates with as much detail as possible when you file issues or PRs. - ## Open an issue If you want to suggest improvements to existing content or notice an error, open an issue. -1. Click the **Create documentation issue** link on the right sidebar. This - redirects you to a GitHub issue page prepopulated with some headers. +1. Click the **Create documentation issue** link on any document. This redirects + you to a GitHub issue page prepopulated with some headers. 2. Describe the issue or suggestion for improvement. Provide as many details as you can. 3. Click **Submit new issue**. After submitting, check in on your issue occasionally or turn on GitHub -notifications. Reviewers and other community members might ask questions before -they can take action on your issue. +notifications. It might take a few days until maintainers and approvers respond. +Reviewers and other community members might ask questions before they can take +action on your issue. + +### Suggesting new content or features + +If you have an idea for new content or a feature, but you aren't sure where it +should go, you can still file an issue. You can also report bugs and security +vulnerabilities. -### Suggesting new content +1. Go to + [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) and + select **New issue** inside the **Issues** tab. -If you have an idea for new content, but you aren't sure where it should go, you -can still file an issue. Either: +1. Select the type of issue that best applies to your request or doubt. -- Choose an existing page in the section you think the content belongs in and - click **Create documentation issue**. -- Go to [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) - and file the issue directly. +1. Fill out the template. + +1. Submit the issue. ## How to file great issues @@ -535,6 +525,24 @@ Keep the following in mind when filing an issue: Respect your fellow contributors. For example, "The docs are terrible" is not helpful or polite feedback. +## Contribute to other repositories + +The OpenTelemetry project contains many repositories. Several of these +repositories contain documentation: user-facing help text, error messages, API +references or code comments. + +If you see text you'd like to improve, use GitHub to search all repositories in +the OpenTelemetry organization. This can help you figure out where to submit +your issue or PR. + +Each repository has its own processes and procedures. Before you file an issue +or submit a PR, read that repository's `README.md`, `CONTRIBUTING.md`, and +`code-of-conduct.md`, if they exist. + +Most repositories use issue and PR templates. Have a look through some open +issues and PRs to get a feel for that team's processes. Make sure to fill out +the templates with as much detail as possible when you file issues or PRs. + ## Other ways to contribute - Visit the [OpenTelemetry community site](/community/). diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contribute/style-guide.md index 11b68aafea15..d018dcf90b1b 100644 --- a/content/en/docs/contribute/style-guide.md +++ b/content/en/docs/contribute/style-guide.md @@ -23,8 +23,17 @@ the site. | OpenTelemetry | OpenTelemetry should always be capitalized. Don't use Open-Telemetry. | | OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. | | Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. | -| Repository | Code repositories. Don't use repo or repos. | +| Repository | Code repository, lowercase when in the middle of a sentence. Don't use "repo" or "repos". | +| OTEP | OpenTelemetry Enhancement Proposal. Write "OTEPs" as plural form. Don't write "OTep" or "otep". | +| OpAMP | Open Agent Management Protocol. Don't write "OPAMP" or "opamp" in descriptions or instructions. | +| OTLP | OpenTelemetry Protocol. Don't write "OTlP" or "otlp" in descriptions or instructions. | +Make sure that proper nouns, such as other CNCF projects or third-party tools, +are properly written and use the original capitalization. For example, write +"PostgreSQL" instead of "postgre". For a full list, check the +[`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml) +file. + See also the [Glossary](/docs/concepts/glossary/) for a list of OpenTelemetry terms and their definition. From c756a04fda8c10031c8efbc7ce4bbbec2a37f92d Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 14:58:03 +0100 Subject: [PATCH 42/62] Glossary entries --- content/en/docs/contribute/style-guide.md | 2 +- static/refcache.json | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contribute/style-guide.md index d018dcf90b1b..6b7a9daadc5e 100644 --- a/content/en/docs/contribute/style-guide.md +++ b/content/en/docs/contribute/style-guide.md @@ -2,7 +2,7 @@ title: Documentation style guide linkTitle: Style guide weight: 40 -slug: style-guide open-telemetry +slug: style-guide open-telemetry postgre textlintrc --- The OpenTelemetry documentation adheres to the diff --git a/static/refcache.json b/static/refcache.json index db86be8aa726..070b00acb2f2 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -483,6 +483,10 @@ "StatusCode": 200, "LastSeen": "2023-10-01T12:48:08.791661-04:00" }, + "https://commonmark.org/": { + "StatusCode": 206, + "LastSeen": "2023-12-13T14:56:57.912039+01:00" + }, "https://community.cncf.io/end-user-community/": { "StatusCode": 200, "LastSeen": "2023-07-03T17:44:06.5954165Z" @@ -1987,6 +1991,10 @@ "StatusCode": 200, "LastSeen": "2023-06-30T08:49:02.328002-04:00" }, + "https://github.com/": { + "StatusCode": 200, + "LastSeen": "2023-12-13T14:56:57.330463+01:00" + }, "https://github.com/Aneurysm9": { "StatusCode": 200, "LastSeen": "2023-06-30T09:32:40.687601-04:00" From 59721c9dc70260539ca6c58f02cbdccfc797284e Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 16:06:15 +0100 Subject: [PATCH 43/62] Final edits --- CONTRIBUTING.md | 167 +++++------------- content/en/docs/contribute/_index.md | 104 +++++++++-- .../en/docs/contribute/blogs-case-studies.md | 116 +++++++----- content/en/docs/contribute/style-guide.md | 2 +- static/refcache.json | 16 ++ 5 files changed, 215 insertions(+), 190 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94a3bcf27a6e..525e46759b6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,46 +1,53 @@ # Contributing to OpenTelemetry.io -Thanks for your interest in contributing to -[OpenTelemetry.io](https://opentelemetry.io/)! Here are a few general guidelines -on contributing and reporting bugs that we ask you to review. Following these -guidelines helps to communicate that you respect the time of the contributors -managing and developing this open source project. In return, they should -reciprocate that respect in addressing your issue, assessing changes, and -helping you finalize your pull requests. In that spirit of mutual respect, we -endeavor to review incoming issues and pull requests, and will close any -lingering issues or pull requests after long times of inactivity. - -Note that all of your interactions in the project are subject to our -[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). -This includes creation of issues or pull requests, commenting on issues or pull -requests, and extends to all interactions in any real-time space e.g., Slack, -Discord, etc. - -Also review the general +**Thanks for your interest in contributing to +[OpenTelemetry.io](https://opentelemetry.io/)!** + +Follow these guidelines helps to communicate that you respect the time of the +contributors managing and developing this open source project. In return, +maintainers and approvers should reciprocate that respect in addressing your +issue, assessing changes, and helping you finalize your pull requests. In that +spirit of mutual respect, we endeavor to review incoming issues and pull +requests, and will close any lingering issues or pull requests after long times +of inactivity. + +## Before you get started + +### Code of Conduct + +All of your interactions in this project are subject to our +[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md) +. This includes the creation of issues or pull requests, commenting on issues or +pull requests, and extends to all interactions in any real-time space, for +example Slack, Discord, and so on. + +### Contributor License Agreement + +Review the general [OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md), -that will provide additional details, especially that you need to sign a +as it provides additional details, especially that you need to sign a Contributor License Agreement (CLA) before you can contribute. -## Found a security issue? +### Found a security issue? -If you discover a security issue, **do not** report it through GitHub. Instead, -follow the steps in our -[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy). +If you discover a security issue, read the +[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy) +before opening an issue. -## Found a problem? +### Found a problem? -If you find a problem with the content of this repository, or you would like to -request an enhancement, [create an issue][new-issue]. +If you find a bug or a problem with the content of this repository, or you would +like to request an enhancement, [create an issue][new-issue]. -Before reporting a new issue, please ensure that the issue was not already -reported or fixed by searching through our +Before reporting a new issue, make sure that the issue was not already reported +or fixed by searching through our [issues list](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc). -When creating a new issue, include a short meaningful title and clear a -description, as much relevant information as possible, and, if possible, a test -case. +When creating a new issue, include a short, meaningful title and a clear +description. Add as much relevant information as you can, and, if possible, a +test case. -## Want to work on an existing issue? +### Want to work on an existing issue? This is the best way how you can help us to make our documentation better! Take a look at issues tagged with @@ -59,64 +66,11 @@ non-community members who have already made contributions to the [OpenTelemetry organization][org]. After confirmation through a maintainer, plan to provide a PR shortly or let maintainers now if you run into any blockers. -## Sending Pull Requests - -Enhancements and fixes to the website are most welcome! - -Before sending a new [pull request][pr] (PR), take a look at existing -[pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) -and -[issues](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) -to see if the proposed change or fix has been discussed in the past, or if the -change was already implemented but not yet released. - -### Quick fixes - -For small changes to a single file, you can edit directly in GitHub by clicking -**Edit this file** button. After forking the repository, follow the instructions -in [Editing files][]. - -However, formatting may still be needed, like reducing line lengths in the -edited file. The options for fixing formatting are: - -- Checking out the project and running the CLI scripts mentioned in - [Submitting a change](#submitting-a-change). -- Commenting `/fix:format` on your pull request to trigger an automated script. - This requires a unique branch name, which can be edited under _View all - branches_ in your fork. - -For larger fixes, follow the -[instructions to setup a development environment](#development) below. - -### PR Guidelines - -Before a PR gets merged, it will sometimes require a few iterations of -review-and-edit. To help us and yourself make this process as easy as possible, -we ask that adhere to the following: - -- If your PR isn't a [quick fix](#quick-fixes), then **work from a fork**: Click - the [Fork](https://github.com/open-telemetry/opentelemetry.io/fork) button at - the top of the repository and clone the fork locally. When you are ready, - raise a PR with the upstream repository. -- **Do not work from the `main`** branch of your fork, but create a PR-specific - branch. -- Ensure that maintainers are - [allowed to apply changes to your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). +## Contributor's guide -### Merge requirements - -- No “changes requested” reviews by approvers, maintainers, technical committee - members, or subject matter experts -- No unresolved conversations -- Approved by at least one approver -- No failing PR checks -- PR branch is up-to-date with the base branch - -> **Important** -> -> Do not worry too much about failing PR checks! Community members will help you -> to get them fixed, by either providing you with instructions how to fix them -> or by fixing them on your behave. +To learn how to contribute fixes and new content to this project, read the +[Contributor's guide](/content/en/docs/contribute), which includes a style guide +and useful information on the review process. ## Development @@ -219,24 +173,6 @@ The website is built from the following content: [content-modules]: https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules -### Submitting a change - -Before submitting a change to the repository, run the following command and -address any reported issues. Also commit any files changed by the `fix` script: - -```sh -npm run test-and-fix -``` - -To separately test and fix issues with your files, run: - -```sh -npm run test # checks but does not update any files -npm run fix # may update files -``` - -To list available NPM scripts, run `npm run`. - ### Submodule changes If you change any content inside of a [content-modules][] submodule, then you'll @@ -255,17 +191,6 @@ submodule itself. > You'll also need to `git fetch --unshallow` the submodule before you can > submit a PR. Alternatively, set `DEPTH=100` and re-fetch submodules. -### Site deploys and PR previews - -If you submit a PR, Netlify will create a [deploy preview][] so that you can -review your changes. Once your PR is merged, Netlify deploys the updated site to -the production server. - -> **Note**: PR previews include _draft pages_, but production builds do not. - -To see deploy logs and more, visit project's [dashboard][] -- Netlify login -required. - ## Approver and Maintainer practices This last section includes guidelines and some common practices used by @@ -302,18 +227,12 @@ approvers and maintainers while doing code reviews: [.nvmrc]: .nvmrc [clone]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository -[dashboard]: https://app.netlify.com/sites/opentelemetry/overview -[deploy preview]: - https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/ -[editing files]: - https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files [fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo [gitpod.io]: https://gitpod.io [gitpod.io/workspaces]: https://gitpod.io/workspaces [hugo]: https://gohugo.io [localhost:1313]: http://localhost:1313 [localhost:8888]: http://localhost:8888 -[netlify]: https://netlify.com [new-issue]: https://github.com/open-telemetry/opentelemetry.io/issues/new/choose [nodejs-rel]: https://nodejs.org/en/about/previous-releases @@ -323,5 +242,3 @@ approvers and maintainers while doing code reviews: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating [nvm-windows]: https://github.com/coreybutler/nvm-windows [org]: https://github.com/open-telemetry -[pr]: - https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 6b1a67e38312..cd51b57ef6ab 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -148,6 +148,9 @@ If a reviewer asks you to make changes: When your review is complete, a reviewer merges your PR and your changes goes live a few minutes later. +{{% alert title="Tip" %}} Comment `/fix:format` on your pull request to trigger +an automated check for formatting issues. {{% /alert %}} + ### Work from a local fork {#fork-the-repo} If you're more experienced with Git, or if your changes are larger than a few @@ -297,23 +300,6 @@ When you are ready to submit a pull request, commit your changes. 1. Once the changes are pushed, GitHub lets you know that you can create a PR. -#### Preview your changes locally {#preview-locally} - -Preview your changes locally before pushing them or opening a pull request. A -preview lets you catch build errors or markdown formatting problems. - -To build and serve the site locally with Hugo, run the following command: - -```shell -npm run serve -``` - -Navigate to `https://localhost:1313` in your web browser to see the local -preview. Hugo watches the changes and rebuilds the site as needed. - -To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or -close the terminal window. - #### Open a pull request from your fork {#open-a-pr} Figure 3 shows the steps to open a PR from your fork to the @@ -387,6 +373,67 @@ Other checks might also fail, including: GitHub also automatically assigns labels to a PR to help reviewers. +#### Fix content issues automatically + +Before submitting a change to the repository, run the following command and +address any reported issues. Also commit any files changed by the `fix` script: + +```sh +npm run test-and-fix +``` + +To separately test and fix issues with your files, run: + +```sh +npm run test # checks but does not update any files +npm run fix # may update files +``` + +To list available NPM scripts, run `npm run`. + +#### Preview your changes locally {#preview-locally} + +Preview your changes locally before pushing them or opening a pull request. A +preview lets you catch build errors or markdown formatting problems. + +To build and serve the site locally with Hugo, run the following command: + +```shell +npm run serve +``` + +Navigate to `https://localhost:1313` in your web browser to see the local +preview. Hugo watches the changes and rebuilds the site as needed. + +To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or +close the terminal window. + +#### Site deploys and PR previews + +If you submit a PR, Netlify will create a [deploy preview][] so that you can +review your changes. Once your PR is merged, Netlify deploys the updated site to +the production server. + +> **Note**: PR previews include _draft pages_, but production builds do not. + +To see deploy logs and more, visit project's [dashboard][] -- Netlify login +required. + +#### PR guidelines + +Before a PR gets merged, it will sometimes require a few iterations of +review-and-edit. To help us and yourself make this process as easy as possible, +we ask that adhere to the following: + +- If your PR isn't a quick fix, then **work from a fork**: Click the + [Fork](https://github.com/open-telemetry/opentelemetry.io/fork) button at the + top of the repository and clone the fork locally. When you are ready, raise a + PR with the upstream repository. +- **Do not work from the `main`** branch of your fork, but create a PR-specific + branch. +- Ensure that maintainers are + [allowed to apply changes to your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). + #### Changes from reviewers Sometimes reviewers commit to your pull request. Before making any other @@ -472,6 +519,23 @@ create a merge conflict. You must resolve all merge conflicts in your PR. The pull request no longer shows any conflicts. +#### Merge requirements + +Pull requests are merged when they comply with the following criteria: + +- All reviews by approvers, maintainers, technical committee members, or subject + matter experts have the status "Approved" +- No unresolved conversations +- Approved by at least one approver +- No failing PR checks +- PR branch is up-to-date with the base branch + +> **Important** +> +> Do not worry too much about failing PR checks! Community members will help you +> to get them fixed, by either providing you with instructions how to fix them +> or by fixing them on your behave. + ## Open an issue If you want to suggest improvements to existing content or notice an error, open @@ -504,7 +568,7 @@ vulnerabilities. 1. Submit the issue. -## How to file great issues +### How to file great issues Keep the following in mind when filing an issue: @@ -548,3 +612,7 @@ the templates with as much detail as possible when you file issues or PRs. - Visit the [OpenTelemetry community site](/community/). - Add your application to the [Registry](/ecosystem). - Submit a [blog post or case study](/docs/contribute/blogs-case-studies/). + +[dashboard]: https://app.netlify.com/sites/opentelemetry/overview +[deploy preview]: + https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/ diff --git a/content/en/docs/contribute/blogs-case-studies.md b/content/en/docs/contribute/blogs-case-studies.md index 5f08e2456ac7..1ef62aabcda5 100644 --- a/content/en/docs/contribute/blogs-case-studies.md +++ b/content/en/docs/contribute/blogs-case-studies.md @@ -11,74 +11,98 @@ and any news that might be relevant to the OpenTelemetry community. This includes end users and developers. Anyone can write a blog post and submit it for review. -## Submit a post +## Before submitting a blog post Blog posts should not be commercial in nature and should consist of original -content that applies broadly to the OpenTelemetry community. Appropriate blog -content includes: +content that applies broadly to the OpenTelemetry community. + +Verify that your intended content broadly applies to the OpenTelemetry Community +. Appropriate content includes: - New OpenTelemetry capabilities - OpenTelemetry projects updates - Updates from Special Interest Groups - Tutorials and walkthroughs -- Thought leadership around OpenTelemetry -- OpenTelemetry Partner OSS integration +- OpenTelemetry Integrations Unsuitable content includes: - Vendor product pitches -- Partner updates without an integration and customer story -To submit a blog post, follow these steps: +To submit a blog post, +[raise an issue](https://github.com/open-telemetry/opentelemetry.io/issues/new?title=New%20Blog%20Post:%20%3Ctitle%3E) +with the title and a short description of your blog post. If you are not a +[Member](https://github.com/open-telemetry/community/blob/main/community-membership.md#member), +you also need to provide a _sponsor_ for your blog post, who is a Member (by +that definition) and who is willing to provide a first review of your blog post. + +If you do not raise an issue before providing your PR, we may request you to do +so before providing a review. + +## Submit a blog post + +You can submit a blog post either by forking this repository and writing it +locally or by using the GitHub UI. In both cases we ask you to follow the +instructions provided by the +[blog post template](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/blog.md). + +**Note**: Before writing a blog post, ask yourself if your content also might be +a good addition to the documentation. If the answer is "yes", create a new issue +or pull request (PR) with your content to get it added to the docs. + +### Fork and write locally + +After you've set up the local fork you can create a blog post using a template. +Follow these steps to create a post from the template: + +1. Run the following command from the repository root: + + ```sh + npx hugo new content/en/blog/2023/short-name-for-post.md + ``` + + If your post has images or other assets, run the following command: + + ```sh + npx hugo new content/en/blog/2023/short-name-for-post/index.md + ``` + +1. Edit the Markdown file at the path you provided in the previous command. The + file is initialized from the blog-post starter under + [archetypes](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/). -1. [Sign the CLA](https://docs.linuxfoundation.org/lfx/easycla/contributors) if - you have not yet done so. +1. Put assets, like images or other files, into the folder you've created. -1. Have a look at the Markdown format for existing blog posts in the - [opentelemetry.io repository](https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/blog). +1. When your post is ready, submit it through a pull request. -1. Write out your blog post in a text editor of your choice. +### Use the GitHub UI -1. On the same link from step 2, select **Create new file**. Paste your content - into the editor. Name the file to match the proposed title of the blog post, - but don’t put the date in the file name. The blog reviewers will work with - you on the final file name and the date the blog will be published. +If you prefer not to create a local fork, you can use the GitHub UI to create a +new post. Follow these steps to add a post using the UI: -1. When you save the file, GitHub will walk you through the pull request - process. +1. Go to the + [blog post template](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/blog.md) + and click on **Copy raw content** at the top right of the menu. -1. A blog post reviewer will review your submission and work with you on - feedback and final details. When the blog post is approved, the blog will be - scheduled for publication. +1. Select + [Create a new file](https://github.com/open-telemetry/opentelemetry.io/new/main). -## Guidelines and expectations +1. Paste the content from the template you copied in the first step. -- Blog posts should not be vendor pitches. +1. Name your file, for example + `content/en/blog/2022/short-name-for-your-blog-post/index.md`. - - Articles must contain content that applies broadly to the OpenTelemetry - community. For example, a submission should focus on upstream OpenTelemetry - as opposed to vendor-specific configurations. - - Links should primarily be to the official OpenTelemetry documentation. When - using external references, links should be diverse - For example a - submission shouldn't contain only links back to a single company's blog. +1. Edit the Markdown file in GitHub. -- Blog posts are not published on specific dates. +1. When your post is ready, select **Propose changes** and follow the + instructions. - - Articles are reviewed by community volunteers. We'll try our best to - accommodate specific timing, but we make no guarantees. - - Many core parts of the OpenTelemetry projects submit blog posts during - release windows, delaying publication times. Consider submitting during a - quieter period of the release cycle. - - If you are looking for greater coordination on post release dates, - coordinating with [CNCF marketing](https://www.cncf.io/about/contact/) is a - more appropriate choice than submitting a blog post. +## Publication timelines -- Blog posts should be relevant to OpenTelemetry users. +The OpenTelemetry blog doesn't follow a strict publication timeline, this means: - - Topics related to participation in or results of OpenTelemetry SIGs - activities are always on topic. - - Posts about other CNCF projects may or may not be on topic. We recommend - asking the blog team before submitting a draft. - - Many CNCF projects have their own blog. These are often a better choice for - posts. There are times of major feature or milestone for a CNCF project that - users would be interested in reading on the OpenTelemetry blog. +- Your blog post will be published when it has all the approvals required. +- Publication can be postponed if needed, but maintainers can't guarantee + publication at or before a certain date. +- Certain blog posts (major announcements) take precedence and may be published + before your blog post. diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contribute/style-guide.md index 6b7a9daadc5e..cd1f93f55d8b 100644 --- a/content/en/docs/contribute/style-guide.md +++ b/content/en/docs/contribute/style-guide.md @@ -2,7 +2,7 @@ title: Documentation style guide linkTitle: Style guide weight: 40 -slug: style-guide open-telemetry postgre textlintrc +cSpell:ignore: style-guide open-telemetry postgre textlintrc --- The OpenTelemetry documentation adheres to the diff --git a/static/refcache.json b/static/refcache.json index 070b00acb2f2..d34535bf139d 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -83,6 +83,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T13:39:44.708765-04:00" }, + "https://app.netlify.com/sites/opentelemetry/overview": { + "StatusCode": 206, + "LastSeen": "2023-12-13T15:27:13.292839+01:00" + }, "https://app.telemetryhub.com/docs": { "StatusCode": 200, "LastSeen": "2023-06-29T12:27:18.815688-04:00" @@ -1003,6 +1007,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T15:46:50.059623-04:00" }, + "https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork": { + "StatusCode": 206, + "LastSeen": "2023-12-13T15:27:14.272624+01:00" + }, "https://docs.google.com/document/d/15vR7D1x2tKd7u3zaTF0yH1WaHkUr2T4hhr7OyiZgmBg/edit#heading=h.4xuru5ljcups": { "StatusCode": 200, "LastSeen": "2023-06-29T15:52:33.514228-04:00" @@ -3735,6 +3743,10 @@ "StatusCode": 200, "LastSeen": "2023-12-12T09:05:06.564186+01:00" }, + "https://github.com/open-telemetry/opentelemetry.io/fork": { + "StatusCode": 200, + "LastSeen": "2023-12-13T15:27:13.947245+01:00" + }, "https://github.com/open-telemetry/opentelemetry.io/issues/new": { "StatusCode": 200, "LastSeen": "2023-06-30T08:31:06.342368-04:00" @@ -6559,6 +6571,10 @@ "StatusCode": 206, "LastSeen": "2023-12-12T09:05:07.468279+01:00" }, + "https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/": { + "StatusCode": 206, + "LastSeen": "2023-12-13T15:27:12.735575+01:00" + }, "https://www.nomadproject.io": { "StatusCode": 206, "LastSeen": "2023-06-30T08:50:51.721695-04:00" From c39c59f5b3f224ddf299fb37986d6c46f6d8d6fe Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 13 Dec 2023 16:06:36 +0100 Subject: [PATCH 44/62] Edit --- content/en/docs/contribute/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contribute/style-guide.md index cd1f93f55d8b..7cd932e06a4e 100644 --- a/content/en/docs/contribute/style-guide.md +++ b/content/en/docs/contribute/style-guide.md @@ -2,7 +2,7 @@ title: Documentation style guide linkTitle: Style guide weight: 40 -cSpell:ignore: style-guide open-telemetry postgre textlintrc +cSpell:ignore: open-telemetry postgre style-guide textlintrc --- The OpenTelemetry documentation adheres to the From 856072e5d3ae1e5b9d503d2b79868e780414c3b9 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 14 Dec 2023 09:31:36 +0100 Subject: [PATCH 45/62] Update content/en/docs/contribute/_index.md Co-authored-by: Severin Neumann --- content/en/docs/contribute/_index.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index cd51b57ef6ab..4b4157dbc75e 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -148,8 +148,12 @@ If a reviewer asks you to make changes: When your review is complete, a reviewer merges your PR and your changes goes live a few minutes later. -{{% alert title="Tip" %}} Comment `/fix:format` on your pull request to trigger -an automated check for formatting issues. {{% /alert %}} +{{% alert title="Tip" %}} + +Comment `/fix:format` on your pull request to trigger +an automated check for formatting issues. + +{{% /alert %}} ### Work from a local fork {#fork-the-repo} From 1e0138b2756023d86709c538bc203d4605c550a5 Mon Sep 17 00:00:00 2001 From: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Date: Thu, 14 Dec 2023 08:35:52 +0000 Subject: [PATCH 46/62] Results from /fix:format --- content/en/docs/contribute/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 4b4157dbc75e..e068431fa708 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -148,10 +148,10 @@ If a reviewer asks you to make changes: When your review is complete, a reviewer merges your PR and your changes goes live a few minutes later. -{{% alert title="Tip" %}} +{{% alert title="Tip" %}} -Comment `/fix:format` on your pull request to trigger -an automated check for formatting issues. +Comment `/fix:format` on your pull request to trigger an automated check for +formatting issues. {{% /alert %}} From ef563020b9fa32dfffc66d66bc27c69bd78afa2a Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 09:52:36 +0100 Subject: [PATCH 47/62] Update content/en/docs/contribute/style-guide.md Co-authored-by: Patrice Chalin --- content/en/docs/contribute/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contribute/style-guide.md index 7cd932e06a4e..7b0d051fed65 100644 --- a/content/en/docs/contribute/style-guide.md +++ b/content/en/docs/contribute/style-guide.md @@ -1,7 +1,7 @@ --- title: Documentation style guide linkTitle: Style guide -weight: 40 +weight: 10 cSpell:ignore: open-telemetry postgre style-guide textlintrc --- From 01acb2ce091ba826f7d3494b3b5dd45695b7fe00 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 09:53:41 +0100 Subject: [PATCH 48/62] Update content/en/docs/contribute/_index.md Co-authored-by: Patrice Chalin --- content/en/docs/contribute/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index e068431fa708..449e3e33403f 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -1,5 +1,5 @@ --- -title: Contribute +title: Contributing description: Learn how to contribute to the OpenTelemetry documentation. weight: 200 cSpell:ignore: linktitle open-telemetry prepopulated repos spacewhite From a34cef783ab75978013e286a15bb9a8b195e3ef7 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 09:53:53 +0100 Subject: [PATCH 49/62] Update content/en/docs/contribute/blogs-case-studies.md Co-authored-by: Patrice Chalin --- content/en/docs/contribute/blogs-case-studies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/contribute/blogs-case-studies.md b/content/en/docs/contribute/blogs-case-studies.md index 1ef62aabcda5..197070c3e892 100644 --- a/content/en/docs/contribute/blogs-case-studies.md +++ b/content/en/docs/contribute/blogs-case-studies.md @@ -1,6 +1,6 @@ --- title: Submit a blog post -linkTitle: Submit a blog post +description: Learn how to submit a blog post. slug: blogs-case-studies weight: 30 cSpell:ignore: open-telemetry From 6d88a727c4de28ff4fc8c3cc9772145d9f88e2b2 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 09:54:18 +0100 Subject: [PATCH 50/62] Update content/en/docs/contribute/_index.md Co-authored-by: Patrice Chalin --- content/en/docs/contribute/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 449e3e33403f..814fe7f7d393 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -1,6 +1,7 @@ --- title: Contributing description: Learn how to contribute to the OpenTelemetry documentation. +aliases: [/docs/contribution-guidelines] weight: 200 cSpell:ignore: linktitle open-telemetry prepopulated repos spacewhite --- From c9a5d8dc789f11ebe5770cd6b9ad7e9ad370eacf Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 09:54:27 +0100 Subject: [PATCH 51/62] Update content/en/docs/contribute/blogs-case-studies.md Co-authored-by: Patrice Chalin --- content/en/docs/contribute/blogs-case-studies.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/docs/contribute/blogs-case-studies.md b/content/en/docs/contribute/blogs-case-studies.md index 197070c3e892..e68744c90197 100644 --- a/content/en/docs/contribute/blogs-case-studies.md +++ b/content/en/docs/contribute/blogs-case-studies.md @@ -1,7 +1,6 @@ --- title: Submit a blog post description: Learn how to submit a blog post. -slug: blogs-case-studies weight: 30 cSpell:ignore: open-telemetry --- From cd90896fcbd129fac03f840413a5f73854a04e5a Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 09:54:36 +0100 Subject: [PATCH 52/62] Update content/en/docs/contribute/blogs-case-studies.md Co-authored-by: Patrice Chalin --- content/en/docs/contribute/blogs-case-studies.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/docs/contribute/blogs-case-studies.md b/content/en/docs/contribute/blogs-case-studies.md index e68744c90197..e3c8600f1c3c 100644 --- a/content/en/docs/contribute/blogs-case-studies.md +++ b/content/en/docs/contribute/blogs-case-studies.md @@ -2,7 +2,6 @@ title: Submit a blog post description: Learn how to submit a blog post. weight: 30 -cSpell:ignore: open-telemetry --- The [OpenTelemetry blog](/blog/) communicates new features, community reports, From b05a7047fe77870f35dd902db35de11f26fbfbbf Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 09:54:47 +0100 Subject: [PATCH 53/62] Update content/en/docs/contribute/_index.md Co-authored-by: Patrice Chalin --- content/en/docs/contribute/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 814fe7f7d393..0ae75f23dcca 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -3,7 +3,7 @@ title: Contributing description: Learn how to contribute to the OpenTelemetry documentation. aliases: [/docs/contribution-guidelines] weight: 200 -cSpell:ignore: linktitle open-telemetry prepopulated repos spacewhite +cSpell:ignore: prepopulated spacewhite --- You can open an issue about OpenTelemetry documentation, or contribute a change From 2215445a9f9b7fdad9e850ae78321bf33e818092 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 09:55:18 +0100 Subject: [PATCH 54/62] Update content/en/docs/contribute/_index.md Co-authored-by: Patrice Chalin --- content/en/docs/contribute/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 0ae75f23dcca..196dddbb4b23 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -1,6 +1,6 @@ --- title: Contributing -description: Learn how to contribute to the OpenTelemetry documentation. +description: Learn how to contribute to OpenTelemetry documentation. aliases: [/docs/contribution-guidelines] weight: 200 cSpell:ignore: prepopulated spacewhite From 2222315dc6eda02ebc12b573b84509b0e57ad06a Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 10:01:23 +0100 Subject: [PATCH 55/62] Rename section --- content/en/docs/{contribute => contributing}/_index.md | 0 content/en/docs/{contribute => contributing}/acknowledgements.md | 1 - .../en/docs/{contribute => contributing}/blogs-case-studies.md | 0 content/en/docs/{contribute => contributing}/style-guide.md | 0 4 files changed, 1 deletion(-) rename content/en/docs/{contribute => contributing}/_index.md (100%) rename content/en/docs/{contribute => contributing}/acknowledgements.md (98%) rename content/en/docs/{contribute => contributing}/blogs-case-studies.md (100%) rename content/en/docs/{contribute => contributing}/style-guide.md (100%) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contributing/_index.md similarity index 100% rename from content/en/docs/contribute/_index.md rename to content/en/docs/contributing/_index.md diff --git a/content/en/docs/contribute/acknowledgements.md b/content/en/docs/contributing/acknowledgements.md similarity index 98% rename from content/en/docs/contribute/acknowledgements.md rename to content/en/docs/contributing/acknowledgements.md index 80c5c81be5e4..c2dd3d55a71f 100644 --- a/content/en/docs/contribute/acknowledgements.md +++ b/content/en/docs/contributing/acknowledgements.md @@ -2,7 +2,6 @@ title: Acknowledgements description: Acknowledgements for sources for content on this site aliases: [/acknowledgements] -weight: 200 cSpell:ignore: Pigram --- diff --git a/content/en/docs/contribute/blogs-case-studies.md b/content/en/docs/contributing/blogs-case-studies.md similarity index 100% rename from content/en/docs/contribute/blogs-case-studies.md rename to content/en/docs/contributing/blogs-case-studies.md diff --git a/content/en/docs/contribute/style-guide.md b/content/en/docs/contributing/style-guide.md similarity index 100% rename from content/en/docs/contribute/style-guide.md rename to content/en/docs/contributing/style-guide.md From 4ca978607e193bfbeb285b91a6fa9300ad07a064 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 10:14:35 +0100 Subject: [PATCH 56/62] Edit README --- CONTRIBUTING.md | 4 +-- README.md | 70 ++++++++++++------------------------------------- 2 files changed, 19 insertions(+), 55 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 525e46759b6b..9a8a73701f1b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,8 +69,8 @@ PR shortly or let maintainers now if you run into any blockers. ## Contributor's guide To learn how to contribute fixes and new content to this project, read the -[Contributor's guide](/content/en/docs/contribute), which includes a style guide -and useful information on the review process. +[Contributor's guide](/content/en/docs/contributing), which includes a style +guide and useful information on the review process. ## Development diff --git a/README.md b/README.md index ae4de4622615..e7d2ddd245a8 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,42 @@ # OTel logo OpenTelemetry.io This is the source repository for the [OpenTelemetry][] website, project -documentation and blog. The site is [built][contributing.md] using [Hugo][] and -hosted on [Netlify][]. +documentation, and blog. The site is [built][contributing.md] using [Hugo][] and +is hosted on [Netlify][]. ## Get involved +To learn how to contribute fixes and new content to this project, read the +[Contributor's guide](/content/en/docs/contributing), which includes a style +guide and useful information on the review process. + If you are new to OpenTelemetry and just get started with it, you are in a perfect position to help us get better: the website and documentation is the entry point for newcomers like you, so if something is unclear or something is -missing [let us know][]! - -Read on to learn about other ways on how you can help. - -## Adding a project to the OpenTelemetry [Registry] - -For details, see [Adding to the registry][]. - -## Submitting a blog post - -You can submit a blog post either by forking this repository and writing it -locally or by using the GitHub UI. In both cases we ask you to follow the -instructions provided by the [blog post template](archetypes/blog.md). - -**Note**: Before writing a blog post, please ask yourself, if your content also -might be a good addition to the documentation. If the answer is yes, create a -new issue/PR with your content to get it added to the docs. +missing [let us know][]. -### Fork & Write locally +### Submit a blog post -Follow the [setup instructions][contributing.md] then, to create a skeletal blog -post, run the following command from the repository root: +For guidance on how to write and submit a blog post, see +[Submit a blog post](/content/en/docs/contributing/blogs-case-studies). -```sh -npx hugo new content/en/blog/2023/short-name-for-post.md -``` +### Add a project to the OpenTelemetry [Registry] -If your post will have images or other assets, instead run: - -```sh -npx hugo new content/en/blog/2023/short-name-for-post/index.md -``` - -Edit the markdown file at the path you provided in the previous command. The -file is initialized from the blog-post starter under [archetypes](archetypes). - -Put assets, if any, like images into the folder created. - -Once your post is ready, submit it through a [pull request][]. - -### Using the GitHub UI - -- Go to the [blog post template](archetypes/blog.md) and click on - `Copy raw content` at the top right of the menu. -- [Create a new file](https://github.com/open-telemetry/opentelemetry.io/new/main). -- Paste the content from the template. -- Name your file, e.g. - `content/en/blog/2022/short-name-for-your-blog-post/index.md` -- Start editing the markdown file. -- Once your post is ready click on `Propose changes` at the bottom. +For details on how to add a project to the OpenTelemetry Registry, see +[Adding to the registry][]. ## Contributing -See [CONTRIBUTING.md][]. - We have curated some issues with the tags [help wanted][] and [good first -issue][]. This should allow you to quickly find a place to contribute +issue][]. This should allow you to quickly find a place to contribute. See +[CONTRIBUTING.md][] for more information. -We (OTel Comms SIG) meet every two weeks on Monday at 9:00 PT. Check out the +We, the OTel Comms SIG, meet every two weeks on Monday at 9:00 PT. Check out the [OpenTelemetry community calendar][] for the Zoom link and any updates to this schedule. Meeting notes are available as a public [Google doc][]. If you have trouble -accessing the doc, please get in touch on [Slack][]. +accessing the doc, get in touch on [Slack][]. Here is a list of community roles with current and previous members: From 050089b26347f72554cc88d4ef9270ad6580de81 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 10 Jan 2024 10:47:49 +0100 Subject: [PATCH 57/62] Final edits --- .htmltest.yml | 1 + README.md | 8 +++----- content/en/docs/contributing/_index.md | 4 ++-- content/en/docs/contribution-guidelines.md | 8 ++++++-- 4 files changed, 12 insertions(+), 9 deletions(-) diff --git a/.htmltest.yml b/.htmltest.yml index 8e0332d90848..5b0e0332f99c 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -8,6 +8,7 @@ TestFilesConcurrently: true IgnoreDirs: - ^blog/(\d+/)?page/\d+ IgnoreInternalURLs: # list of paths + - /docs/contribution-guidelines/ IgnoreURLs: # list of regexs of paths or URLs to be ignored - ^/docs/instrumentation/\w+/(api|examples)/$ - ^/docs/instrumentation/net/(metrics-api|traces-api)/ diff --git a/README.md b/README.md index e7d2ddd245a8..80bab85a71bd 100644 --- a/README.md +++ b/README.md @@ -22,13 +22,13 @@ For guidance on how to write and submit a blog post, see ### Add a project to the OpenTelemetry [Registry] -For details on how to add a project to the OpenTelemetry Registry, see -[Adding to the registry][]. +For details on how to add a project to the OpenTelemetry Registry, see [Adding +to the registry][]. ## Contributing We have curated some issues with the tags [help wanted][] and [good first -issue][]. This should allow you to quickly find a place to contribute. See +issue][]. This should allow you to quickly find a place to contribute. See [CONTRIBUTING.md][] for more information. We, the OTel Comms SIG, meet every two weeks on Monday at 9:00 PT. Check out the @@ -85,8 +85,6 @@ already contributed][contributors]! [hugo]: https://gohugo.io [netlify]: https://netlify.com [opentelemetry]: https://opentelemetry.io -[pull request]: - https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request [registry]: https://opentelemetry.io/ecosystem/registry/ [opentelemetry community calendar]: https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com diff --git a/content/en/docs/contributing/_index.md b/content/en/docs/contributing/_index.md index 196dddbb4b23..ce2e833284bb 100644 --- a/content/en/docs/contributing/_index.md +++ b/content/en/docs/contributing/_index.md @@ -278,7 +278,7 @@ When you are ready to submit a pull request, commit your changes. (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) - modified: content/en/docs/contribute/new-content/contributing-content.md + modified: content/en/docs/file-you-are-editing.md no changes added to commit (use "git add" and/or "git commit -a") ``` @@ -616,7 +616,7 @@ the templates with as much detail as possible when you file issues or PRs. - Visit the [OpenTelemetry community site](/community/). - Add your application to the [Registry](/ecosystem). -- Submit a [blog post or case study](/docs/contribute/blogs-case-studies/). +- Submit a [blog post or case study](/docs/contributing/blogs-case-studies/). [dashboard]: https://app.netlify.com/sites/opentelemetry/overview [deploy preview]: diff --git a/content/en/docs/contribution-guidelines.md b/content/en/docs/contribution-guidelines.md index e30a94dfe6a7..a09510f1cd42 100644 --- a/content/en/docs/contribution-guidelines.md +++ b/content/en/docs/contribution-guidelines.md @@ -5,10 +5,14 @@ toc_hide: true --- OpenTelemetry is an open source project, and we gladly accept new contributions -and contributors. Please see the CONTRIBUTING.md file in each SIG repository for +and contributors. See the CONTRIBUTING.md file in each SIG repository for information on getting started. -## Contributing to the OpenTelemetry Documentation +## Contribute to the OpenTelemetry Documentation + +To learn how to contribute fixes and new content to this project, read the +[Contributor's guide](/docs/contributing), which includes a style guide and +useful information on the review process. Individual SIGs may maintain documentation above and beyond what is offered here, but we strive for accurate general guidance on using the project from our From 29873452b4f3cfd1db61d23df4ca6053e0cd5e1a Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 11 Jan 2024 10:09:42 +0100 Subject: [PATCH 58/62] Fixes --- README.md | 2 +- content/en/docs/contributing/_index.md | 2 +- .../contributing/{blogs-case-studies.md => blog.md} | 2 +- content/en/docs/contributing/style-guide.md | 12 +++++++----- 4 files changed, 10 insertions(+), 8 deletions(-) rename content/en/docs/contributing/{blogs-case-studies.md => blog.md} (99%) diff --git a/README.md b/README.md index 80bab85a71bd..716841e21c0d 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ missing [let us know][]. ### Submit a blog post For guidance on how to write and submit a blog post, see -[Submit a blog post](/content/en/docs/contributing/blogs-case-studies). +[Submit a blog post](/content/en/docs/contributing/blog). ### Add a project to the OpenTelemetry [Registry] diff --git a/content/en/docs/contributing/_index.md b/content/en/docs/contributing/_index.md index ce2e833284bb..f4d471831a14 100644 --- a/content/en/docs/contributing/_index.md +++ b/content/en/docs/contributing/_index.md @@ -616,7 +616,7 @@ the templates with as much detail as possible when you file issues or PRs. - Visit the [OpenTelemetry community site](/community/). - Add your application to the [Registry](/ecosystem). -- Submit a [blog post or case study](/docs/contributing/blogs-case-studies/). +- Submit a [blog post or case study](/docs/contributing/blog/). [dashboard]: https://app.netlify.com/sites/opentelemetry/overview [deploy preview]: diff --git a/content/en/docs/contributing/blogs-case-studies.md b/content/en/docs/contributing/blog.md similarity index 99% rename from content/en/docs/contributing/blogs-case-studies.md rename to content/en/docs/contributing/blog.md index e3c8600f1c3c..1a245ec94364 100644 --- a/content/en/docs/contributing/blogs-case-studies.md +++ b/content/en/docs/contributing/blog.md @@ -1,5 +1,5 @@ --- -title: Submit a blog post +title: Blog description: Learn how to submit a blog post. weight: 30 --- diff --git a/content/en/docs/contributing/style-guide.md b/content/en/docs/contributing/style-guide.md index 7b0d051fed65..9109823f7d1c 100644 --- a/content/en/docs/contributing/style-guide.md +++ b/content/en/docs/contributing/style-guide.md @@ -5,11 +5,13 @@ weight: 10 cSpell:ignore: open-telemetry postgre style-guide textlintrc --- -The OpenTelemetry documentation adheres to the -[Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) -and the -[Google Developer Documentation Style Guide](https://developers.google.com/style) -. The following sections contain guidance that is specific to the OpenTelemetry +We don't have an official style guide yet, but the current OpenTelemetry +documentation style is inspired by the following style guides: + +- [Google Developer Documentation Style Guide](https://developers.google.com/style) +- [Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) + +The following sections contain guidance that is specific to the OpenTelemetry project. ## OpenTelemetry.io word list From f4d26776293c66b4dea41d41ca868da2362e6c94 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 11 Jan 2024 14:00:08 +0100 Subject: [PATCH 59/62] Remove HTML test --- .htmltest.yml | 1 - content-modules/opentelemetry-specification | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/.htmltest.yml b/.htmltest.yml index 5b0e0332f99c..8e0332d90848 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -8,7 +8,6 @@ TestFilesConcurrently: true IgnoreDirs: - ^blog/(\d+/)?page/\d+ IgnoreInternalURLs: # list of paths - - /docs/contribution-guidelines/ IgnoreURLs: # list of regexs of paths or URLs to be ignored - ^/docs/instrumentation/\w+/(api|examples)/$ - ^/docs/instrumentation/net/(metrics-api|traces-api)/ diff --git a/content-modules/opentelemetry-specification b/content-modules/opentelemetry-specification index b064af8f1545..c6520a732870 160000 --- a/content-modules/opentelemetry-specification +++ b/content-modules/opentelemetry-specification @@ -1 +1 @@ -Subproject commit b064af8f1545ca61ca99d6a07c37f9fb33186e51 +Subproject commit c6520a73287040ca16499cba62cea1b3508dc4da From 7acc40e02e8d965987b42640b453e12dd4677c3c Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 11 Jan 2024 14:02:03 +0100 Subject: [PATCH 60/62] Updated refcache --- static/refcache.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/static/refcache.json b/static/refcache.json index d34535bf139d..ad318b4702db 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -7055,6 +7055,10 @@ "StatusCode": 206, "LastSeen": "2023-06-29T18:41:53.764072-04:00" }, + "https://www.w3.org/TR/baggage/#baggage-string": { + "StatusCode": 206, + "LastSeen": "2024-01-11T14:01:22.958369+01:00" + }, "https://www.w3.org/TR/baggage/#header-content": { "StatusCode": 206, "LastSeen": "2023-12-16T15:16:50.350520378Z" @@ -7123,6 +7127,10 @@ "StatusCode": 200, "LastSeen": "2023-06-29T18:43:02.782058-04:00" }, + "https://yaml.org/spec/1.2.2/": { + "StatusCode": 206, + "LastSeen": "2024-01-11T14:01:23.459474+01:00" + }, "https://youtu.be/9iaGG-YZw5I": { "StatusCode": 200, "LastSeen": "2023-06-01T17:03:14.742262-04:00" From 61fe8d8905f5c6a99e384b4e4d8fcd08e26e1b87 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 11 Jan 2024 14:07:58 +0100 Subject: [PATCH 61/62] Fix refcache --- static/refcache.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/static/refcache.json b/static/refcache.json index 12a79ec1315a..a2ad3f784d54 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -7057,11 +7057,7 @@ }, "https://www.w3.org/TR/baggage/#baggage-string": { "StatusCode": 206, -<<<<<<< HEAD - "LastSeen": "2024-01-11T14:01:22.958369+01:00" -======= "LastSeen": "2024-01-11T06:07:13.666570443Z" ->>>>>>> main }, "https://www.w3.org/TR/baggage/#header-content": { "StatusCode": 206, From 5a617108a4895b995aca0e31688ce2d33f694f09 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 11 Jan 2024 14:28:13 +0100 Subject: [PATCH 62/62] Fix period --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a8a73701f1b..f15f09d170cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,8 +16,8 @@ of inactivity. ### Code of Conduct All of your interactions in this project are subject to our -[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md) -. This includes the creation of issues or pull requests, commenting on issues or +[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). +This includes the creation of issues or pull requests, commenting on issues or pull requests, and extends to all interactions in any real-time space, for example Slack, Discord, and so on.
Configuration parameters