knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Consolidate all "docs" help info into single location (#3437) 

* consolidate docs how-to guides

* fix template linking

* consolidate and organize

* update links

* fix link

* fix typos

and
offensive term

* Update help/contributor/how-to/formatting.md

Co-authored-by: Samia Nneji <snneji@vmware.com>

* Update help/contributor/how-to/formatting.md

Co-authored-by: Samia Nneji <snneji@vmware.com>

* Update help/contributor/gettingstarted.md

Co-authored-by: Samia Nneji <snneji@vmware.com>

* Update help/faqs.md

Co-authored-by: Samia Nneji <snneji@vmware.com>

* Update help/contributor/publishing.md

Co-authored-by: Samia Nneji <snneji@vmware.com>

* Update help/contributor/publishing.md

Co-authored-by: Samia Nneji <snneji@vmware.com>

* recover review comments

* typo

Co-authored-by: Samia Nneji <snneji@vmware.com>
This commit is contained in:
RichieEscarez 2021-04-26 10:57:40 -07:00 committed by GitHub
parent e3170d4c4a
commit 3af9db6781
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
31 changed files with 2255 additions and 633 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

358
CONTRIBUTING.md
View File

@ -1,349 +1,15 @@
---
_build:
render: never
list: never
---
(This guide only appears on GitHub, not the website, because it
**intentionally** does not include YAML front-matter.)
- [Your first contribution](#your-first-contribution)
- [Code of conduct](#code-of-conduct)
- [Contributor license agreements](#contributor-license-agreements)
- [Fixing Issues (Pull Requests)](#fixing-issues--pull-requests-)
- [Reporting Issues](#reporting-issues)
- [Getting involved](#getting-involved)
- [Working group meetings](#working-group-meetings)
- [Workflow](#workflow)
- [New Content](#new-content)
- [Refining and Reviewing Content](#refining-and-reviewing-content)
- [Tech Writer Guide](#tech-writer-guide)
- [Type of documentation](#type-of-documentation)
- [Documentation Structure](#documentation-structure)
- [Branches](#branches)
- [Tools and Style](#tools-and-style)
- [Engineer Guide](#engineer-guide)
- [Putting your docs in the right place](#putting-your-docs-in-the-right-place)
All information about contributing to the Knative documentation has been moved
into a single location:
**First off, thanks for taking the time to contribute!**
#### [Go to the How-to guides for Knative docs contributors](https://knative.dev/help/)
The following are guidelines for contributing to the Knative documentation.
These are just guidelines, not rules. Use your best judgment, and feel free to
propose changes to this document in a pull request.
# Your first contribution
## Code of conduct
Knative follows the
[Knative Code of Conduct](https://github.com/knative/community/blob/main/CODE-OF-CONDUCT.md).
By participating, you are expected to uphold this code. Please report
unacceptable behavior to <knative-code-of-conduct@googlegroups.com>.
## Contributor license agreements
Knative requires the [Google CLA](https://cla.developers.google.com). Important:
You must fill out the CLA with the same email address that you used to create
your GitHub account.
Once you are CLA'ed, we'll be able to accept your pull requests. This is
necessary because you own the copyright to your changes, even after your
contribution becomes part of this project. So this agreement simply gives us
permission to use and redistribute your contributions as part of the project.
Note: Your contributions are verified using the email address for which you use
to sign the CLA. Therefore,
[setting your GitHub account to private](https://help.github.com/en/articles/setting-your-commit-email-address)
is unsupported because all commits from private accounts are sent from the
`noreply` email address.
## Fixing Issues (Pull Requests)
<!-- This could use a pass to be more focused on what a PR submitter should do at the start of the process. -->
Here's what generally happens when you open a PR against the `knative/docs`
repo:
1. One of the assigned repo maintainers will triage the PR by assigning
relative priority, adding appropriate labels, and performing an initial
documentation review.
2. If the PR involves significant technical changes, for example new features,
or new and changed sample code, the PR is assigned to a Subject Matter
Expert (SME), typically an engineer working on Knative, for technical review
and approval.
3. When both the technical writers and SMEs are satisfied with the quality of
the writing and the technical accuracy of the content, the PR can be merged.
A PR requires two labels before it can merge: `lgtm` and `approved`.
- The SME is responsible for reviewing the technical accuracy and adding the
`lgtm` label.
- The
[Knative technical writers](https://github.com/knative/docs/blob/main/OWNERS_ALIASES)
are who provide the `approved` label when the content meets quality,
clarity, and organization standards (see [Style Guide](#style-guide)).
We appreciate contributions to the docs, so if you open a PR we will help you
get it merged. You can also post in the `#docs`
[Slack channel](https://knative.slack.com/) to get input on your ideas or find
areas to contribute before creating a PR.
## Reporting Issues
<!-- This could use a pass to reduce the overhead for filing new issues,
and to consolidate items more easily during issue triage. -->
Knative uses Github issues to track documentation issues and requests. If you
see a problem with the documentation that you're not sure how to fix, submit an
issue using the following steps:
1. Check the [Knative docs issues list](https://github.com/knative/docs/issues)
before creating an issue to avoid making a duplicate.
2. Use the [correct template](https://github.com/knative/docs/issues/new) for
your new issue. There are two templates available:
- **Bug report**: If you're reporting an error in the existing
documentation, use this template. This could be anything from broken
samples to typos. When you create a bug report, include as many details as
possible and include suggested fixes to the issue. If you know which
Knative component your bug is related to, you can assign the appropriate
[Working Group Lead](https://github.com/knative/community/blob/main/working-groups/WORKING-GROUPS.md).
- **Feature request**: For upcoming changes to the documentation or requests
for more information on a particular subject.
Note that code issues should be filed against the
[individual Knative repositories](http://github.com/knative), while
documentation issues should go in the
[`knative/docs` repo](https://github.com/knative/docs/issues). If the issue is
specific to the <https://knative.dev> website, open the issue in the
[`knative/website` repo](https://github.com/knative/website/issues).
# Getting involved
There are a couple of different ways to get started with contributing to the
Knative documentation:
- Look for a
[Good First Issue](https://github.com/knative/docs/labels/kind%2Fgood-first-issue)
in the backlog.
- Try out Knative and
[send us feedback](https://github.com/knative/docs/issues/new?template=docs-feature-request.md).
For example, run through the [install guides](./docs/install/) and then try
[Getting Started with Knative Serving](./docs/serving/getting-started-knative-app.md)
or [Getting Started With Eventing](./docs/eventing/getting-started.md).
Keep a
[friction log](https://devrel.net/developer-experience/an-introduction-to-friction-logging)
of your experience and attach it to a feature request, or use it to open your
first set of PRs. Examples:
- What was difficult for you?
- Did you stumble on something because the steps weren't clear?
- Was a dependency not mentioned?
## Working group meetings
The
[Knative Documentation Working Group](https://github.com/knative/community/blob/main/working-groups/WORKING-GROUPS.md#documentation)
meeting info and times.
[Click here](https://calendar.google.com/calendar/embed?src=knative.team_9q83bg07qs5b9rrslp5jor4l6s%40group.calendar.google.com)
The Working Group meetings are used to discuss documentation strategy and
policy; we expect individual PR review to happen mostly asynchronously via
GitHub, and [Slack](https://slack.knative.dev).
# Workflow
There are roughly two workflows: writing / contributing new content, and
refining and reviewing existing content.
## New Content
We expect most new content to be written by the subject matter expert (SME)
which would be the contributor who actually worked on the feature or example.
When writing new content, keep the following in mind:
- Write one [type of documentation](#type of documentation) per page.
- If possible, follow the style/template of other documents of the same type.
- Focus mostly on technical correctness; structure and language should be
roughly correct, but don't need heavy review in this phase.
The goal of adding new content is to get technically correct documentation into
the repo before it is lost. Tech Writers may provide some quick guidance on
getting documentation into the correct location, but won't be providing a
detailed list of items to change.
## Refining and Reviewing Content
Once the raw documentation has made it into the repo, tech writers and other
communications experts will review and revise the documentation to make it
easier to consume. This will be done as a second PR; it's often easier for the
tech writers to clean up or rewrite a section of prose than to teach an engineer
what to do, and most engineers trust the wordsmithing the tech writers produce
more than their own.
When revising the content, the tech writer will create a new PR and send it to
the original author to ensure that the content is technically correct; they may
also ask a few clarifying questions, or add details such as diagrams or notes if
needed. It's not necessarily expected that tech writers will actually execute
the steps of a tutorial — it's expected that the SME is responsible for a
working tutorial or how-to.
# Tech Writer Guide
## Type of documentation
Keep in mind the audience (Developers or Administrators) and type of document
when organizing and reviewing documentation. See
https://documentation.divio.com/ for a more in-depth discussion of documentation
types.
## Documentation Structure
**TODO: link to intended documentation layout.** A general warning about
[Conway's Law](https://en.wikipedia.org/wiki/Conway%27s_law): documents will
naturally tend to be distributed by team that produced them. Try to fight this,
and organize documents based on where the _reader_ will look for them. (i.e. all
tutorials together, maybe with indications as to which components they use,
rather than putting all serving tutorials in one place)
Note that some reference documentation may be automatically generated and
checked in to the docs repo. This _should_ be indicated by both a `README.md` in
the top-level directory where the generation happens, and by a header at the top
of the documentation. The `README.md` should include documentation on the
original source material for the documentation as well as the commands needed to
regenerate the documentation. If possible, the generation of documentation the
should be performed automatically via nightly (GitHub actions) automation.
In some cases, the right place for a document may not be on the docs website — a
blog post, documentation within a code repo, or a vendor site may be the right
place. Be generous with offering to link to such locations; documents in the
main documentation come with an ongoing cost of keeping up to date.
## Branches
Knative attempts to
[support the last 4 releases](https://github.com/knative/community/blob/main/mechanics/RELEASE-VERSIONING-PRINCIPLES.md).
By default, new documentation should be written on the `main` branch and then
cherry-picked to the release branches if needed. Note that the default view of
<https://knative.dev/> is of the most recent release branch, which means that
changes to `main` don't show up unless explicitly cherrypicked. This also
means that documentation changes for a release _should be made during the
development cycle_, rather than at the last minute or after the release.
The
[`/cherrypick` tool](https://github.com/kubernetes/test-infra/tree/master/prow/external-plugins/cherrypicker)
can be use to automatically pull back changes from `main` to previous releases
if necessary.
## Tools and Style
Knative documentation follows the
[Google Developer Documentation Style Guide](https://developers.google.com/style/).
Use this as a reference for writing style questions.
Knative uses several sets of tools to manage pull requests (PR)s and issues in a
more fine-grained way than GitHub permissions allow. In particular, you'll
regularly interact with
[Prow](https://github.com/kubernetes/test-infra/tree/master/prow) to categorize
and manage issues and PRs. Prow allows control of specific GitHub functionality
without granting full "write" access to the repo (which would allow rewriting
history and other dangerous operations). You'll most often use the following
commands, but Prow will also chime in on most bugs and PRs with a link to all
the known commands:
- `/assign @user1 @user2` to assign an issue or PR to specific people for review
or approval.
- `/lgtm` and `/approve` to approve a PR. Note that _anyone_ may `/lgtm` a PR,
but only someone listed in an `OWNERS` file may `/approve` the PR. A PR needs
both an approval and an LGTM — the `/lgtm` review is a good opportunity for
non-approvers to practice and develop reviewing skills. `/lgtm` is removed
when a PR is updated, but `/approve` is sticky — once applied, anyone can
supply an `/lgtm`.
- Both Prow (legacy) and GitHub actions (preferred) can run tests on PRs; once
all tests are passing and a PR has the `lgtm` and `approved` labels, Prow will
submit the PR automatically.
- You can also use Prow to manage labels on PRs with `/kind ...`,
`/good-first-issue`, or `/area ...`
- See [Branches](#branches) for details on the `/cherrypick` command.
# Engineer Guide
## Putting your docs in the right place
There are currently two general types of Knative docs, either contributor
related content, or external-facing user content.
### Contributor-focused content
- _Documentation_: Includes content that is component specific and relevant only
to contributors of a given component. Contributor focused documentation is
located in the corresponding `docs` folder of that component's repository. For
example, if you contribute code to the Knative Serving component, you might
need to add contributor focused information into the `docs` folder of the
[knative/serving repo](https://github.com/knative/serving/tree/main/docs/).
- _Code samples_: Includes contributor related code or samples. Code or samples
that are contributor focused also belong in their corresponding component's
repo. For example, Eventing specific test code is located in the
[knative/eventing tests](https://github.com/knative/eventing/tree/main/test)
folder.
### User-focused content
- _Documentation_: Content for developers or administrators using Knative. This
documentation belongs in the
[`knative/docs` repo](https://github.com/knative/docs). All content in
`knative/docs` is published to https://knative.dev.
- _Code samples_: Includes user-facing code samples and their accompanying
step-by-step instructions. Code samples add a particular burden because they
sometimes get out of date quickly; as such, not all code samples may be
suitable for the docs repo.
- **Knative owned and maintained**: Includes code samples that are actively
maintained and e2e tested. To ensure content is current and balance
available resources, only the code samples that meet the following
requirements are located in the `docs/[*component*]/samples` folders of the
`knative/docs` repo:
- _Actively maintained_ - The code sample has an active Knative team member
who has committed to regular maintenance of that content and ensures that
the code is updated and working for every product release.
- _Receives regular traffic_ - To avoid hosting and maintaining unused or
stale content, if code samples are not being viewed and fail to receive
attention or use, those samples will be moved into the
“[community maintained](https://github.com/knative/docs/tree/main/community/samples)”
set of samples.
- _Passes e2e testing_ - All code samples within
`docs/[*component*]/samples` folders must align with (and pass) the
[`e2e` tests](https://github.com/knative/docs/tree/main/test).
- **Community owned and maintained samples**: For sample code which doesn't
meet the above criteria, put the code in a separate repository and link to
it [from this document](community/samples/README.md). These samples might
not receive regular maintenance. It is possible that a sample is no longer
current and is not actively maintained by its original author. While we
encourage a contributor to maintain their content, we acknowledge that it's
not always possible for certain reasons, for example other commitments and
time constraints.
While a sample might be out of date, it could still provide assistance and help
you get up-and-running with certain use-cases. If you find that something is not
right or contains outdated info, open an
[Issue](https://github.com/knative/docs/issues/new). The sample might be fixed
if bandwidth or available resource exists, or the sample might be taken down and
archived into the last release branch where it worked.
**Quick links**:
* [Docs help](https://knative.dev/help/contributor/)
* New content templates:
* [Documentation](https://github.com/knative/docs/tree/main/template-docs-page.md) -- Instructions and a template that
you can use to help you add new documentation.
* [Blog](https://github.com/knative/docs/tree/main/template-blog-page.md) -- Instructions and a template that
you can use to help you post to the Knative blog.
* [Website help](https://knative.dev/help/contributor/publishing)
* [Maintainer help](https://knative.dev/help/maintainer/)

61
DEVELOPMENT.md
View File

@ -6,54 +6,17 @@ _build:
(This guide only appears on GitHub, not the website, because it
**intentionally** does not include YAML front-matter.)
# Development
All information about contributing to the Knative documentation has been moved
into a single location:
This doc explains how to setup a development environment so you can get started
[contributing](https://www.knative.dev/contributing/) to `Knative Docs`. Also
take a look at:
#### [Go to the How-to guides for Knative docs contributors](https://knative.dev/help/)
- [The pull request workflow](https://www.knative.dev/contributing/contributing/#pull-requests)
## Prerequisites
Follow the instructions below to set up your development environment. Once you
meet these requirements, you can make changes and
Before submitting a PR, see also [CONTRIBUTING.md](./CONTRIBUTING.md).
### Sign up for GitHub
Start by creating [a GitHub account](https://github.com/join), then setup
[GitHub access via SSH](https://help.github.com/articles/connecting-to-github-with-ssh/).
### Checkout your fork
To check out this repository:
1. Create your own
[fork of this repo](https://help.github.com/articles/fork-a-repo/)
1. Clone it to your machine:
```shell
mkdir -p ${GOPATH}/src/knative.dev
cd ${GOPATH}/src/knative.dev
git clone git@github.com:${YOUR_GITHUB_USERNAME}/docs.git
cd docs
git remote add upstream https://github.com/knative/docs.git
git remote set-url --push upstream no_push
```
_Adding the `upstream` remote sets you up nicely for regularly
[syncing your fork](https://help.github.com/articles/syncing-a-fork/)._
### Run website locally
Refer to this [doc](https://github.com/knative/website/blob/main/DEVELOPMENT.md) in the website repo.
### Common Troubleshooting issues for PRs
1. The CLA check fails even though you have signed the CLA. This may occur if you accept and commit suggestions in a pull request from another person's account, because the email address of that account doesn't match the address on record for the CLA. The commit will show up as co-authored, which can cause issues if your public email address has not signed the CLA.
1. One or more tests are failing. If you do not see a specific error related to a change you made, and instead the errors are related to timeouts, try rerunning the test at a later time. There are running tasks that could result in timeouts or rate limiting if your test runs at the same time.
1. Other Issues/Unsure - reach out in the #docs slack channel and someone will be happy to help out.
**Quick links**:
* [Docs help](https://knative.dev/help/contributor/)
* New content templates:
* [Documentation](https://github.com/knative/docs/tree/main/template-docs-page.md) -- Instructions and a template that
you can use to help you add new documentation.
* [Blog](https://github.com/knative/docs/tree/main/template-blog-page.md) -- Instructions and a template that
you can use to help you post to the Knative blog.
* [Website help](https://knative.dev/help/contributor/publishing)
* [Maintainer help](https://knative.dev/help/maintainer/)

70
blog/README.md
View File

@ -1,65 +1,21 @@
=======
---
_build:
render: never
list: never
---
# Knative blog
All information about contributing to the Knative documentation has been moved
into a single location:
The Knative blog is owned by the [Documentation working group](https://knative.dev/community/contributing/working-groups/working-groups/#documentation) and run by the [Editorial Team](#leadership).
#### [Go to the How-to guides for Knative docs contributors](https://knative.dev/help/)
This section covers documentation, processes, and roles for the [Knative blog](https://knative.dev/blog/).
## Leadership
- **Technical Editors:** [Lionel Villard](https://github.com/lionelvillard), [Evan Anderson](https://github.com/evankanderson)
- **Copy Editors:** [Ashleigh Brennan](https://github.com/abrennan89), [Caroline Lee](https://github.com/carieshmarie), [María Cruz](https://github.com/macruzbar)
- **Blog Community Managers:** [María Cruz](https://github.com/macruzbar), [Jonatas Baldin](https://github.com/jonatasbaldin)
## Contact
- Slack: [#docs](https://knative.slack.com/archives/C9CV04DNJ)
## Submit a Post
Anyone can write a blog post and submit it for review. Commercial content is not allowed. Please refer to the [blog guidelines](#blog-guidelines) for more guidance.
To submit a blog post, follow the steps below.
1. [Sign the Contributor License Agreements](https://github.com/knative/community/blob/main/CONTRIBUTING.md#contributor-license-agreements) if you have not yet done so.
1. Familiarize yourself with the Markdown format for existing blog posts in the [docs repository](https://github.com/knative/docs/tree/main/blog). Blog posts are categorized into different directories. You can explore the directories to find examples.
1. Write your blog post in a text editor of your choice.
1. (Optional) If you need help with markdown, check out [StakEdit](https://stackedit.io/app#) or read [GitHub's formatting syntax](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax) for more information.
1. Choose a directory in the [docs repository](https://github.com/knative/docs/tree/main/blog), and click **Create new file**.
1. Paste your content into the editor and save it. Name the file in the following way: *[BLOG] Your proposed title* , 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 on which the blog will be published.
1. When you save the file, GitHub will walk you through the pull request (PR) process.
1. A reviewer is assigned to all pull requests automatically. The reviewer checks your submission, and works with you on feedback and final details. When the pull request is approved, the blog will be scheduled for publication.
1. Ping editorial team members on Slack [#docs](https://knative.slack.com/archives/C9CV04DNJ) channel with a link to your recently created PR.
### Blog Guidelines
#### Suitable content:
- **Original content only**
- Knative [new feature releases and project updates](## Communicating new project releases)
- Tutorials and demos [start a blog](https://github.com/knative/docs/pull/2511)
- Use cases
- Content that is specific to a vendor or platform about Knative installation and use
#### Unsuitable Content:
- Blogs that do not address Knative in any way
- Content that doesn't interact with Knative APIs or interfaces
- Vendor pitches
## Communicating new project releases
**Scheduled releases:** The Knative project has a release every 6 weeks, and we need your help communicating new changes to our community! If you would like to contribute a blog post to the Knative blog, please consider writing about the latest changes to the project. Ideally, there should be a single blog post for every release version, for example, 0.17; 0.18; 0.19. The title convention should be: *Version [version number] release - [date]*. Release blog contributors should write a summary of the changes and select up to 3 highlights of the current release to write about.
**Big changes to the project.** Big changes to the project require a deep dive blog that describes the new feature in detail and give examples of the new functionality.
## Review Process
After a blog post is submitted as a PR, it is automatically assigned to a reviewer.
Each blog post requires a `lgtm` label from at least one person in the editorial team. Once the necessary labels are in place, one of the reviewers will add an `approved` label, and schedule publication of the blog post.
### Service level agreement (SLA)
Blog posts can take up to **1 week** to review. If you'd like to request an expedited review, please say so on your message when you ping the editorial team on Slack.
**Quick links**:
* [Docs help](https://knative.dev/help/contributor/)
* New content templates:
* [Documentation](https://github.com/knative/docs/tree/main/template-docs-page.md) -- Instructions and a template that
you can use to help you add new documentation.
* [Blog](https://github.com/knative/docs/tree/main/template-blog-page.md) -- Instructions and a template that
you can use to help you post to the Knative blog.
* [Website help](https://knative.dev/help/contributor/publishing)
* [Maintainer help](https://knative.dev/help/maintainer/)

119
docs/reference/api/README.md
View File

@ -1,3 +1,4 @@
## View the latest release
The reference documentation for the latest release of the Knative is available
@ -10,118 +11,8 @@ The API source files are located at:
- [Serving API](./serving.md)
- [Eventing API](./eventing/eventing.md)
## Updating API Reference docs (for Knative maintainers)
### Generating API docs
The Knative API reference documentation is manually generated using the
[`gen-api-reference-docs.sh`](../../../hack/) tool. If you need to generate a new
version of the API docs for a recent update or for a new release, you can use
the following steps.
To learn more about the tool, see the
[gen-crd-api-reference-docs](https://github.com/ahmetb/gen-crd-api-reference-docs)
reference page.
### Before you begin
You must meet the following requirements to run the `gen-api-reference-docs.sh`
tool:
- You need the following software installed:
- [`git`](https://git-scm.com/download/)
- [`go` version 1.11+](https://golang.org/dl/)
- Clone [knative/docs](https://github.com/knative/docs) locally. For example:
`git clone git@github.com:knative/docs.git`
### Generating the API
To generate a version of the API:
1. Ensure that your `GOPATH` is empty. The `gen-api-reference-docs.sh` script
will result in the `GOPATH should not be set` error if your `GOPATH` is
configured. You view the value by running the following command:
```
echo $GOPATH
```
If your `GOPATH` is already configured, temporarily clear the `GOPATH` value
by running the following command:
```
export GOPATH=""
```
1. Locate the commits or tags that correspond to the version of the API that you
want to generate:
- [Serving](https://github.com/knative/serving/releases/)
- [Eventing](https://github.com/knative/eventing/releases/)
1. To run the `gen-api-reference-docs.sh` command from the `hack` directory, you
specify the commits or tags for each of the corresponding Knative component
variables (`KNATIVE_[component_name]_COMMIT`):
```
cd hack
KNATIVE_SERVING_COMMIT=[commit_or_tag] \
KNATIVE_EVENTING_COMMIT=[commit_or_tag] \
./gen-api-reference-docs.sh
```
where `[commit_or_tag]` is the commit or tag in the specific repo that
represents the version of the API that you want to generate. Also see the
[example](#example) below.
**Result**
The `gen-api-reference-docs.sh` tool generates the API in a `tmp` folder.
After a successful build, the tool automatically opens that folder in the
`tmp` directory.
If the script fails, there are a couple possible causes.
* If you get the
`F1116 15:21:23.549503 63473 main.go:129] no API packages found in ./pkg/apis`
error, check if a new version of the script is available:
https://github.com/ahmetb/gen-crd-api-reference-docs/tags
The script is kept up-to-date with changes that go into the Kubernetes API.
As Knative adds support for those APIs, you might need to make sure the
corresponding
[script `gen-crd-api-reference-docs` version](https://github.com/knative/docs/blob/main/hack/gen-api-reference-docs.sh#L26)
is used.
* If you get the
`F0807 13:58:20.621526 168834 main.go:444] type invalid type has kind=Unsupported which is unhandled`
error, the import target might have moved. There might be other causes for that error but view
[#2054](https://github.com/knative/docs/pull/2054) (and the linked Issues) for details about how we handled that error
in the past.
1. Copy the generated API files into the `docs/reference` directory of your
knative/docs clone.
1. The linter now fails for content with trailing whitespaces. Use a tool of your choice to
remove all trailing whitespace. For example, search for and remove: `\s+$`
You can now perform the necessary steps to open a PR, complete a review, and
merge the new API files into the appropriate branch of the `knative/docs` repo.
See the [contributor flow](/DOCS-CONTRIBUTING.md) for details
about requesting changes in the `knative/docs` repo.
### Example
To build a set of Knative API docs for v0.18, you can use the `v0.18.0` the tags
from each of the Knative component repositories, like
[Serving v0.18.0](https://github.com/knative/serving/tree/v0.18.0). If you want to
use a commit for Serving v0.18.0, you would use
[850b7c](https://github.com/knative/serving/commit/850b7cca7d7701b052420a030f2308d19938d45e).
Using tags from each repo, you would run the following command to generate the
v0.18.0 API source files:
```
KNATIVE_SERVING_COMMIT=v0.18.0 \
KNATIVE_EVENTING_COMMIT=v0.18.0 \
./gen-api-reference-docs.sh
```
See the
[API build instructions](https://www.knative.dev/help/maintainer/building-api-output)
in the Knative documentation maintainer section.

50
docs/smoketest.md
View File

@ -1,7 +1,3 @@
# Spacer Title
<br>
# Hidden smoketest page
Use this page to test your changes and ensure that there are not any issues,
@ -30,9 +26,14 @@ Below are a set of site elements that have causes issues in the past.
The following use the
[`readfile` shortcode](https://github.com/knative/website/blob/main/layouts/shortcodes/readfile.md)
Shortcode: <code>{<code>{< readfile file="../hack/reference-docs-gen-config.json" code="true" lang="json" >}</code>}</code>
renders as:
{{< readfile file="../hack/reference-docs-gen-config.json" code="true" lang="json" >}}
{{< readfile file="../Gopkg.toml" code="true" lang="toml" >}}
Shortcode: <code>{<code>{< readfile file="./serving/samples/cloudevents/cloudevents-nodejs/service.yaml" code="true" lang="yaml" >}</code>}</code>
renders as:
{{< readfile file="./serving/samples/cloudevents/cloudevents-nodejs/service.yaml" code="true" lang="yaml" >}}
## Install version numbers and Clone branch commands
@ -42,27 +43,46 @@ added in-line with the
(uses the define values from
[config/\_default/params.toml](https://github.com/knative/website/blob/main/config/_default/params.toml))
1. Shortcode: <code>{<code>{% version %}</code>}</code>
1. Shortcode: <code>{<code>{< version >}</code>}</code>
renders as: {{< version >}}
Example:
`kubectl apply version/{{% version %}}/is-the-latest/docs-version.yaml`
`kubectl apply version/{{< version >}}/is-the-latest/docs-version.yaml`
1. Shortcode: <code>{<code>{% version override="v0.2.2" %}</code>}</code>
1. Shortcode: <code>{<code>{< version override="v0.2.2" >}</code>}</code>
renders as: {{< version override="v0.2.2" >}}
Example:
`kubectl apply the-version-override/{{% version override="v0.2.2" %}}/is-manually-specified.yaml`
`kubectl apply the-version-override/{{< version override="v0.2.2" >}}/is-manually-specified.yaml`
1. Shortcode: <code>{<code>{% version patch=".20" %}</code>}</code>
1. Shortcode: <code>{<code>{< version patch=".20" >}</code>}</code>
renders as: {{< version patch=".20" >}}
Example:
`kubectl apply this-is-a-point-release/{{% version patch=".20" %}}/filename.yaml`
`kubectl apply this-is-a-point-release/{{< version patch=".20" >}}/filename.yaml`
1. Shortcode: <code>{<code>{% branch %}</code>}</code>
1. Shortcode: <code>{<code>{< branch >}</code>}</code>
renders as: {{< branch >}}
Example:
`git clone -b "{{% branch %}}" https://github.com/knative/docs knative-docs`
`git clone -b "{{< branch >}}" https://github.com/knative/docs knative-docs`
1. Shortcode: <code>{<code>{% branch override="release-0.NEXT" %}</code>}</code>
1. Shortcode: <code>{<code>{< branch override="release-0.NEXT" >}</code>}</code>
renders as: {{< branch override="release-0.NEXT" >}}
Example:
`git clone -b "{{% branch override="release-0.NEXT" %}}" https://github.com/knative/docs knative-docs`
`git clone -b "{{< branch override="release-0.NEXT" >}}" https://github.com/knative/docs knative-docs`
## Tabs
How to include tabbed content in your page. Note that you can set a default tab.
{{< tabs name="tabs_example" default="Include example" >}}
{{< tab name="Regular example" >}}
This is a regular example tab.
{{< /tab >}}
{{< tab name="Include example" >}}
{{% readfile file="./serving/samples/multi-container/service.yaml" code="true" lang="yaml" %}}
{{< /tab >}}
{{< /tabs >}}

21
help/_index.md Normal file
View File

@ -0,0 +1,21 @@
---
title: "How-to guides for contributing to Knative documentation"
linkTitle: "How-to guides for docs"
weight: "10"
type: "docs"
showlandingtoc: "true"
---
<!-- Original file: https://github.com/knative/docs/pull/3269 -->
Welcome to the *help* for Knative documentation.
**First off, thanks for taking the time to contribute!**
The following are guidelines for contributing to the user facing Knative
documentation, including help for new docs, blog posts, and other website
related information.
These are just guidelines, not rules. Use your best judgment, and
feel free to open PRs and propose changes to these documents.

10
help/contributor/_index.md Normal file
View File

@ -0,0 +1,10 @@
---
title: "Knative documentation contributor guides"
linkTitle: "Contributor guides"
weight: "10"
type: "docs"
showlandingtoc: "true"
---
Learn how to contribute content to the Knative documentation and publish
to the `knative.dev` website.

117
help/contributor/gettingstarted.md Normal file
View File

@ -0,0 +1,117 @@
---
title: "Joining the project and getting started"
linkTitle: "Join"
weight: 10
type: "docs"
---
## Join to become a contributor
You must meet the following prerequisites before you are able to contribute to
the docs. The following steps are specific to docs contributions.
For more information about contributing to the Knative project, see the
[Knative contribution guidelines](https://github.com/knative/community/blob/main/contributing.md).
1. If you don't already have an account, you must create
[a new GitHub account](https://github.com/join).
1. Become a Knative Member by subscribing to
[knative-dev@googlegroups.com](https://groups.google.com/forum/#!forum/knative-dev).
[Learn more about community roles](https://github.com/knative/community/tree/main/ROLES.md)
1. Read and follow the
[Knative Code of Conduct](https://github.com/knative/community/blob/main/CODE-OF-CONDUCT.md).
By participating, you are expected to uphold this code. Please report all
unacceptable behavior to <knative-code-of-conduct@googlegroups.com>.
1. Sign the contributor license agreements (CLA):
Knative requires the [Google CLA](https://cla.developers.google.com).
**Important:** You must fill out the CLA with the same email address that you
used to create your GitHub account. Also see the note about private accounts.
Once you are CLA'ed, we'll be able to accept your pull requests. This is
necessary because you own the copyright to your changes, even after your
contribution becomes part of this project. So this agreement simply gives us
permission to use and redistribute your contributions as part of the project.
Private accounts not supported: Your contributions are verified using the
email address for which you use to sign the CLA. Therefore,
[setting your GitHub account to private](https://help.github.com/en/articles/setting-your-commit-email-address)
is unsupported because all commits from private accounts are sent from the
`noreply` email address.
## Tips: Get involved
There are a couple of different ways to get started with contributing to the
Knative documentation:
- Look for a
[Good First Issue](https://github.com/knative/docs/labels/kind%2Fgood-first-issue)
in the backlog.
- Try out Knative and
[send us feedback](https://github.com/knative/docs/issues/new?template=docs-feature-request.md).
For example, run through the [install guides](../../docs/install/) and then try
[Getting Started with Knative Serving](../../docs/serving/getting-started-knative-app.md)
or [Getting Started With Eventing](../../docs/eventing/getting-started.md).
Keep a
[friction log](https://devrel.net/developer-experience/an-introduction-to-friction-logging)
of your experience and attach it to a feature request, or use it to open your
first set of PRs. Examples:
- What was difficult for you?
- Did you stumble on something because the steps weren't clear?
- Was a dependency not mentioned?
## Get help from the community
- [#docs on the Knative Slack](https://slack.knative.dev) -- The #docs channel
is the best place to go if you have questions about making changes to the
documentation. We're happy to help!
- Attend a Documentation working group meeting
-- Come join us to ask questions, get help, and meet other docs contributors.
[See meeting details, times, and the agenda](https://github.com/knative/community/blob/main/working-groups/WORKING-GROUPS.md#documentation)
## Workflow overview
We expect most new content to be written by the subject matter expert (SME)
which would be the contributor who actually worked on the feature or example.
When writing new content, focus mostly on technical correctness and thoroughness
(it must include all the steps that are required by the target audience).
Language should be roughly correct, but don't need heavy review in this phase.
The goal of adding new content is to get technically correct documentation into
the repo before it is lost. Tech Writers may provide some quick guidance on
getting documentation into the correct location, but won't be providing a
detailed list of items to change.
Once the raw documentation has made it into the repo, tech writers and other
communications experts will review and revise the documentation to make it
easier to consume. This will be done as a second PR; it's often easier for the
tech writers to clean up or rewrite a section of prose than to teach an engineer
what to do, and most engineers trust the wordsmithing the tech writers produce
more than their own.
When revising the content, the tech writer will create a new PR and send it to
the original author to ensure that the content is technically correct; they may
also ask a few clarifying questions, or add details such as diagrams or notes if
needed. It's not necessarily expected that tech writers will actually execute
the steps of a tutorial — it's expected that the SME is responsible for a
working tutorial or how-to.
## What's next
- [Learn how to use GitHub and clone the `knative/docs` repo](./how-to/github.md)
- [Read the "How to" guides](./how-to/)
- [Learn how to post to the blog](./new-blog/)
- [Learn how the website works](./publishing.md)

7
help/contributor/how-to/_index.md Normal file
View File

@ -0,0 +1,7 @@
---
title: "How-to for documentation"
linkTitle: "How-tos"
weight: "40"
type: "docs"
showlandingtoc: "true"
---

72
help/contributor/how-to/codesamples.md Normal file
View File

@ -0,0 +1,72 @@
---
title: "Code samples"
linkTitle: ""
weight: 100
type: "docs"
---
There are currently two general types of content that focus on code samples,
either internal contributor content, or external-facing user content.
## Contributor-focused content
- _Documentation_: Includes content that is component specific and relevant only
to contributors of a given component. Contributor focused documentation is
located in the corresponding `docs` folder of that component's repository. For
example, if you contribute code to the Knative Serving component, you might
need to add contributor focused information into the `docs` folder of the
[knative/serving repo](https://github.com/knative/serving/tree/main/docs/).
- _Code samples_: Includes contributor related code or samples. Code or samples
that are contributor focused also belong in their corresponding component's
repo. For example, Eventing specific test code is located in the
[knative/eventing tests](https://github.com/knative/eventing/tree/main/test)
folder.
## User-focused content
- _Documentation_: Content for developers or administrators using Knative. This
documentation belongs in the
[`knative/docs` repo](https://github.com/knative/docs). All content in
`knative/docs` is published to https://knative.dev.
- _Code samples_: Includes user-facing code samples and their accompanying
step-by-step instructions. Code samples add a particular burden because they
sometimes get out of date quickly; as such, not all code samples may be
suitable for the docs repo.
- **Knative owned and maintained**: Includes code samples that are actively
maintained and e2e tested. To ensure content is current and balance
available resources, only the code samples that meet the following
requirements are located in the `docs/[*component*]/samples` folders of the
`knative/docs` repo:
- _Actively maintained_ - The code sample has an active Knative team member
who has committed to regular maintenance of that content and ensures that
the code is updated and working for every product release.
- _Receives regular traffic_ - To avoid hosting and maintaining unused or
stale content, if code samples are not being viewed and fail to receive
attention or use, those samples will be moved into the
“[community maintained](https://github.com/knative/docs/tree/main/community/samples)”
set of samples.
- _Passes e2e testing_ - All code samples within
`docs/[*component*]/samples` folders must align with (and pass) the
[`e2e` tests](https://github.com/knative/docs/tree/main/test).
- **Community owned and maintained samples**: For sample code which doesn't
meet the above criteria, put the code in a separate repository and link to
it [from this page](https://github.com/knative/docs/tree/main/community/samples/README.md).
These samples might not receive regular maintenance. It is possible that a
sample is no longer current and is not actively maintained by its original
author. While we encourage a contributor to maintain their content, we
acknowledge that it's not always possible for certain reasons, for example
other commitments and time constraints.
While a sample might be out of date, it could still provide assistance and help
you get up-and-running with certain use-cases. If you find that something is not
right or contains outdated info, open an
[Issue](https://github.com/knative/docs/issues/new). The sample might be fixed
if bandwidth or available resource exists, or the sample might be taken down and
archived into the last release branch where it worked.

113
help/contributor/how-to/formatting.md Normal file
View File

@ -0,0 +1,113 @@
---
title: "Formatting standards and conventions"
linkTitle: "Formatting standards"
weight: 40
type: "docs"
---
This page shows the formatting standards for the Knative documentation. Knative uses
Markdown to markup the content and Hugo with the Docsy template, to build the website. To ensure
consistency across our documentation, we have agreed on these formatting standards.
[Learn about the Hugo/Docsy requirements for each page](./frontmatter.md)
## Linking: Use relative URLs
For all links within the Knative content, use relative linking (also known as
[relative URLs](https://www.w3.org/TR/WD-html40-970917/htmlweb.html#h-5.1.2)).
Linking conventions:
- Links between files in the same directory must be prefixed with: `./`
Example: `[Shortcodes](./shortcodes.md)` renders as [Shortcodes](./shortcodes.md)
- To link across folders, add `../` for each directory that you must travel
towards the root docs directory.
Example: `[FAQs](../../faqs.md)` renders as [FAQs](../../faqs.md)
#### Background
Early on in the content development, all of the documentation was author in the
GitHub repos and since then, there are many contributors who value the ability
to consume the documentation from within the repo. In addition, the main
Markdown editor and renderer when authoring Knative docs is the GitHub UI.
Therefore, we continue to **use relative URLs throughout** to ensure that all
the links work as expected, both when clicked in the GitHub UI and on knative.dev.
Hugo has it's own syntax for linking across your content and treats
the content across the site as a single version of docs (including a Hugo
specific definition of relative links: *relative to the website domain*).
Unfortunately, that type of linking renders markdown content unusable from with
the GitHub repos and does not allow for easy versioning/archiving.
## Don't use capitalization for emphasis
Only use the original capitalization found in the code or configuration files
when referencing those values directly. Use back-ticks \`\` around the
referenced value to make the connection explicit. For example, use
`IstioRoleBinding`, not `Istio Role Binding` or `istio role binding`.
If you are not referencing values or code directly, use normal sentence
capitalization, for example, "The Knative role binding configuration takes place
in a YAML file."
## Use angle brackets for placeholders
Use angle brackets for placeholders in commands or code samples. Tell the reader
what the placeholder represents. For example:
1. Display information about a pod:
$ kubectl describe pod <pod-name>
Where `<pod-name>` is the name of one of your pods.
## Use **bold** to emphasize user interface elements
|Do | Don't
|------------------|------
|Click **Fork**. | Click "Fork".
|Select **Other**. | Select 'Other'.
## Use _italics_ to emphasize 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**.
Use the `gloss` shortcode and add glossary entries for new terms.
## Use `back-ticks` around file names, directories, and paths
|Do | Don't
|-------------------------------------|------
|Open the `foo.yaml` file. | Open the foo.yaml file.
|Go to the `/content/en/docs/tasks` directory. | Go to the /content/en/docs/tasks directory.
|Open the `/data/args.yaml` file. | Open the /data/args.yaml file.
## Use `back-ticks` around inline code and commands
|Do | Don't
|----------------------------|------
|The `foo run` command creates a `Deployment`. | The "foo run" command creates a `Deployment`.
|For declarative management, use `foo apply`. | For declarative management, use "foo apply".
Use code-blocks for commands you intend readers to execute. Only use inline code
and commands to mention specific labels, flags, values, functions, objects,
variables, modules, or commands.
* Learn how to include code snippets from source files using the
[`readfile`](https://github.com/knative/website/blob/main/layouts/shortcodes/readfile.md)
shortcode. See an [example](https://knative.dev/docs/smoketest/#code-samples).
## Use `back-ticks` around object field names
|Do | Don't
|-----------------------------------------------------------------|------
|Set the value of the `ports` field in the configuration file. | Set the value of the "ports" field in the configuration file.
|The value of the `rule` field is a `Rule` object. | The value of the "rule" field is a `Rule` object.

118
help/contributor/how-to/frontmatter.md Normal file
View File

@ -0,0 +1,118 @@
---
title: "Front matter"
linkTitle: ""
weight: 30
type: "docs"
---
The front matter is YAML code in between triple-dashed lines at the top of each
file and provides important management options for our content. For example, the
front matter allows us to ensure that existing links continue to work for pages
that are moved or deleted entirely. This page explains the front matter
features that are currently available in knative.dev.
The following example shows a front matter with all the required fields
filled by placeholders:
```
---
title: "<page_title>"
linkTitle: "<optional_shorter_menu_title>"
weight: <weight>
type: "docs"
aliases:
- <previously-published-at-this-URL>
---
```
More details and options for Hugo frontmatter: https://gohugo.io/content-management/front-matter/#predefined
## Required front matter fields
The following table shows descriptions for all the **required** fields:
|Field | Description
|-------------------|------------
| `title` | The page's title.
| `linkTitle` | Optional: A short version of the page title that renders nicely in the navigation menu.
| `weight` | The order of the page relative to the other pages in the directory.
| `type` | Specify `docs`. Required for our docs versioning process.
| `aliases` | Optional: URLs of past pages that you want redirected to "this" page.
[See how to define the Knative front matter](../new-docs/docs-page.md).
### Rename, move, or delete pages
When you move pages or delete them completely, you must ensure that the existing
links to those pages continue to work. The `aliases` field in the front matter
helps you meet this requirement. Add the path to the page before the move or
deletion to the `aliases` field. Hugo implements automatic redirects from the
old URL to the new URL for our users.
On the _target page_, which is the page where you want users to land, add the `<path>`
of the _original page_ to the front-matter as follows:
```
aliases:
- </path/from/root>
```
### Example
In this example, the following file is deleted: `/docs/install/knative-with-any-k8s.md`
To ensure that anyone who tries to navigate to the deleted file gets redirected
to its replacement, you must add `/docs/install/knative-with-any-k8s.md` under
`aliases`.
In the `/docs/install/_index.md` file, you add the
`/docs/install/knative-with-any-k8s` URL path without the file type suffix,
under `aliases`:
```
---
title: "Installing Knative"
weight: 05
type: "docs"
aliases:
- /docs/install/knative-with-any-k8s
- /docs/install/knative-with-aks
- /docs/install/knative-with-ambassador
- /docs/install/knative-with-contour
- /docs/install/knative-with-docker-for-mac
- /docs/install/knative-with-gke
- /docs/install/knative-with-gardener
- /docs/install/knative-with-gloo
- /docs/install/knative-with-icp
- /docs/install/knative-with-iks
- /docs/install/knative-with-microk8s
- /docs/install/knative-with-minikube
- /docs/install/knative-with-minishift
- /docs/install/knative-with-pks
- /docs/install/any-kubernetes-cluster
showlandingtoc: "false"
---
```
Notice that multiple files redirect to the
`/docs/install/_index.md` file, all indented under `aliases`, prefixed with `-`,
and with paths starting from root.
View the
[`docs/install/_index.md`](https://raw.githubusercontent.com/knative/docs/main/docs/install/_index.md)
file in the repository.
## Optional front matter fields
However, Hugo supports many front matter fields and this page only covers those
implemented on knative.dev.
The following table shows the most commonly used **optional** fields:
|Field | Description
|-------------------|------------
|`linkTitle` | A shorter version of the title that is used to ensure that the text fits within the left navigation menu.
|`showlandingtoc`. | For `_index.md` files only. By default, an in-page TOC is added to the body of the page. Specify `"false"` to hide the in-page TOC.

204
help/contributor/how-to/github.md Normal file
View File

@ -0,0 +1,204 @@
---
title: "GitHub workflow for Knative documentation"
linkTitle: "Using GitHub"
weight: 10
type: "docs"
---
Learn how to use GitHub and contribute to the `knative/docs` repo.
At a high-level, you must setup and know the following to get started:
- [Set up your local machine](#clone)
- [Open Issues](#issues)
- [Create Pull Requests](#prs)
- [Manage PRs and Issues with Prow](#prow)
## Set up your local machine{#clone}
To check out your fork of the `knative/docs` repository:
1. Create your own
[fork of the `knative/docs` repo](https://help.github.com/articles/fork-a-repo/)
1. Configure
[GitHub access through SSH](https://help.github.com/articles/connecting-to-github-with-ssh/).
1. Clone your fork to your machine and set the `upstream` remote to the
`knative/docs` repository:
```shell
mkdir -p ${GOPATH}/src/knative.dev
cd ${GOPATH}/src/knative.dev
git clone git@github.com:${YOUR_GITHUB_USERNAME}/docs.git
cd docs
git remote add upstream https://github.com/knative/docs.git
git remote set-url --push upstream no_push
```
You are now able to open PRs, start reviews, and contribute fixes the
`knative/docs` repo. See the following sections to learn more.
**Important**: Remember to regularly
[syncing your fork](https://help.github.com/articles/syncing-a-fork/).
## Reporting documentation issues{#issues}
<!-- This could use a pass to reduce the overhead for filing new issues,
and to consolidate items more easily during issue triage. -->
Knative uses Github issues to track documentation issues and requests. If you
see a problem with the documentation that you're not sure how to fix, submit an
issue using the following steps:
1. Check the [Knative docs issues list](https://github.com/knative/docs/issues)
before creating an issue to avoid making a duplicate.
2. Use the [correct template](https://github.com/knative/docs/issues/new) for
your new issue. There are two templates available:
- **Bug report**: If you're reporting an error in the existing
documentation, use this template. This could be anything from broken
samples to typos. When you create a bug report, include as many details as
possible and include suggested fixes to the issue. If you know which
Knative component your bug is related to, you can assign the appropriate
[Working Group Lead](https://github.com/knative/community/blob/main/working-groups/WORKING-GROUPS.md).
- **Feature request**: For upcoming changes to the documentation or requests
for more information on a particular subject.
Note that product behavior or code issues should be filed against the
[individual Knative repositories](http://github.com/knative).
Documentation issues should go in the
[`knative/docs` repo](https://github.com/knative/docs/issues) but if the issue
is specific to the look or behavior of the <https://knative.dev> website, open
the issue in the
[`knative/website` repo](https://github.com/knative/website/issues).
## Fixing documentation issues (Opening PRs){#prs}
The Knative documentation follows the standard
[GitHub collaboration flow](https://guides.github.com/introduction/flow/)
for Pull Requests (PRs).
General details about how to open a PR are covered in the
[Knative guidelines](https://github.com/knative/community/).
Note that PRs for fixes to the look or behavior of the <https://knative.dev>
website, must be opened the
[`knative/website` repo](https://github.com/knative/website/pulls).
<!-- This could use a pass to be more focused on what a PR submitter should do at the start of the process. -->
1. [Ensure that your fork is up-to-date](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork).
1. [Create a branch in your fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository).
1. Locate or create the file that you want to fix:
- If you are updating an existing page, locate that file and begin making
changes.
For example, from any page on `knative.dev`, you can click the
pencil icon in the upper right corner to open that page in GitHub.
- If you are adding new content, you must follow the
"new docs" instructions.
1. To edit a file, use the new branch that you created in your fork.
- Navigate to that same file within your fork using the GitHub UI.
- Open that file from in your local clone.
1. Create the Pull Request in the
[`knative/docs` repo](https://github.com/knative/docs/pulls).
1. [Assign an owner to the PR](#assigning-owners-and-reviewers)
to request a review.
Here's what generally happens after you send the PR for review:
1. One of the assigned repo maintainers will triage the PR by assigning
relative priority, adding appropriate labels, and performing an initial
documentation review.
2. If the PR involves significant technical changes, for example new features,
or new and changed sample code, the PR is assigned to a Subject Matter
Expert (SME), typically an engineer working on Knative, for technical review
and approval.
3. When both the technical writers and SMEs are satisfied with the quality of
the writing and the technical accuracy of the content, the PR can be merged.
A PR requires two labels before it can merge: `lgtm` and `approved`.
- The SME is responsible for reviewing the technical accuracy and adding the
`lgtm` label.
- The
[Knative technical writers](https://github.com/knative/docs/blob/main/OWNERS_ALIASES)
are who provide the `approved` label when the content meets quality,
clarity, and organization standards (see [Style Guide](#style-guide)).
We appreciate contributions to the docs, so if you open a PR we will help you
get it merged. You can also post in the `#docs`
[Slack channel](https://knative.slack.com/) to get input on your ideas or find
areas to contribute before creating a PR.
## Assigning owners and reviewers
All PRs should be assigned to a single owner ("_Assignee_"). It's best to set
the "Assignee" and include other stakeholders as "Reviewers" rather than leaving
it unassigned or allowing [Prow](https://prow.k8s.io/command-help) to auto
assign reviewers.
Use the `/assign` command to set the owner. For example: `/assign @owner_id`
**For code related changes**, initially set the owner of your PR to the SME who
should review for technical accuracy. If you don't know who the appropriate
owner is, nor who your reviewers should be for your PR, you can assign the
[current working group lead](https://github.com/knative/community/tree/main/WORKING-GROUPS.md) of the related component.
If you want to notify and include other stakeholders in your PR review, use the
`/cc` command. For example: `/cc @stakeholder_id1 @stakeholder_id2`
## Reviewing PRs
[See the Knative community guidelines about reviewing PRs](https://github.com/knative/community/blob/main/reviewing.md)
## Using Prow to manage PRs and Issues{#prow}
Knative uses several sets of tools to manage pull requests (PR)s and issues in a
more fine-grained way than GitHub permissions allow. In particular, you'll
regularly interact with
[Prow](https://github.com/kubernetes/test-infra/tree/master/prow) to categorize
and manage issues and PRs. Prow allows control of specific GitHub functionality
without granting full "write" access to the repo (which would allow rewriting
history and other dangerous operations). You'll most often use the following
commands, but Prow will also chime in on most bugs and PRs with a link to all
the known commands:
- `/assign @user1 @user2` to assign an issue or PR to specific people for review
or approval.
- `/lgtm` and `/approve` to approve a PR. Note that _anyone_ may `/lgtm` a PR,
but only someone listed in an `OWNERS` file may `/approve` the PR. A PR needs
both an approval and an LGTM — the `/lgtm` review is a good opportunity for
non-approvers to practice and develop reviewing skills. `/lgtm` is removed
when a PR is updated, but `/approve` is sticky — once applied, anyone can
supply an `/lgtm`.
- Both Prow (legacy) and GitHub actions (preferred) can run tests on PRs; once
all tests are passing and a PR has the `lgtm` and `approved` labels, Prow will
submit the PR automatically.
- You can also use Prow to manage labels on PRs with `/kind ...`,
`/good-first-issue`, or `/area ...`
- See the [Branches](./structure/#branches) section for details about how
to use the `/cherrypick` command.

57
help/contributor/how-to/shortcodes.md Normal file
View File

@ -0,0 +1,57 @@
---
title: "Shortcodes: Website widgets"
linkTitle: "Shortcodes"
weight: "50"
type: "docs"
---
A list and examples of the custom shortcodes that are currently used and available
in knative.dev.
STAUS: This page is in "draft state" and needs to be completed.
## Knative custom shortcodes
https://github.com/knative/website/tree/main/layouts/shortcodes
All of these Knative shortcodes are added as examples in the smoketest pages
- [root](https://knative.dev/smoketest/)
- [/docs/](https://knative.dev/docs/smoketest/)
## Learn more about shortcodes
- Hugo shortcodes https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes
- How to create custom shortcodes https://gohugo.io/templates/shortcode-templates/
- Docsy shortcodes https://www.docsy.dev/docs/adding-content/shortcodes/
- Other shortcodes https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes
### Includes
Include files and code samples with the `readfile` shortcode:
https://github.com/knative/website/blob/main/layouts/shortcodes/readfile.md
### Dynamic variables
Use them to reduce release maintenance and ensure content accuracy.
The following variable are dynamically populated based on the URL of the content in knative.dev:
- The [branch shortcode](https://github.com/knative/website/blob/main/layouts/shortcodes/branch.md) <code>{<code>{< branch >}</code>}</code> renders: `{{< branch >}}`
- The [version shortcode](https://github.com/knative/website/blob/main/layouts/shortcodes/version.md) <code>{<code>{< version >}</code>}</code> renders: `{{< version >}}`
### Artifacts
https://github.com/knative/website/pull/129/files
### Tabs
https://github.com/knative/website/pull/124

98
help/contributor/how-to/structure.md Normal file
View File

@ -0,0 +1,98 @@
---
title: "Content structure"
linkTitle: ""
weight: 20
type: "docs"
---
**TODO: link to intended documentation layout.** A general warning about
[Conway's Law](https://en.wikipedia.org/wiki/Conway%27s_law): documents will
naturally tend to be distributed by team that produced them. Try to fight this,
and organize documents based on where the _reader_ will look for them. (i.e. all
tutorials together, maybe with indications as to which components they use,
rather than putting all serving tutorials in one place)
In some cases, the right place for a document may not be on the docs website — a
blog post, documentation within a code repo, or a vendor site may be the right
place. Be generous with offering to link to such locations; documents in the
main documentation come with an ongoing cost of keeping up to date.
[Learn about documenting code samples](./codesamples.md)
## Branches
Knative attempts to
[support the last 4 releases](https://github.com/knative/community/blob/main/mechanics/RELEASE-VERSIONING-PRINCIPLES.md).
By default, new documentation should be written on the `main` branch and then
cherry-picked to the release branches if needed. Note that the default view of
<https://knative.dev/> is of the most recent release branch, which means that
changes to `main` don't show up unless explicitly cherrypicked. This also
means that documentation changes for a release _should be made during the
development cycle_, rather than at the last minute or after the release.
The
[`/cherrypick` tool](https://github.com/kubernetes/test-infra/tree/master/prow/external-plugins/cherrypicker)
can be use to automatically pull back changes from `main` to previous releases
if necessary.
### Putting your docs in the right place
Generally, the `knative/docs` repo contains Knative specific user-facing content
and blog content.
Contributor-focused content belongs in one of the other Knative code
repositories (`knative/serving`, `knative/eventing`, etc.).
### Docs versioning
Each version of the Knative docs are separated by branches in the knative/docs
repository. The `main` branch represents the "in active development" version
of the docs. All content in the `main` branch is renders on Knative.dev under
the **Pre-release** menu and might not be tested nor working.
Content in all the other branches of the knative/docs repo
represent "released versions of the docs" and use the naming convention
`release-#.#` where `#.#` is the version of Knative to which those docs
correspond.
#### Choosing the correct branch
It is likely that your docs contribution is either for new or changed features
in the product, or for a fix or update existing content.
- **New or changed features**: If you are adding or updating documentation for a
new or changed feature, you likely want to open your PR against the `main`
branch. All pre-release content for active Knative development belongs in
[`main`](https://github.com/knative/docs/tree/main/).
- **Fixes and updates**: If you find an issue in a past release, for example a
typo or out-of-date content, you likely need to open multiple and subsequent
PRs. If not a followup PR, at least add the "`cherrypick` labels" to your
original PR to indicate in which of the past release that your change affects.
For example, if you find a typo in a page of the `v0.5` release, then that
page in the `main` branch likely also has that typo.
To fix the typo:
1. Open a PR against the
[`main`](https://github.com/knative/docs/tree/main/) branch.
1. Add one or more `cherrypick-#.#` labels to that PR to indicate which of
the past release branches should also be fixed. Generally, we only
maintain the most recent numbered release.
1. If you want to complete the fix yourself (**best practice**), you then
open a subsequent PR by running `git cherry-pick [COMMIT#]` against the
`release-0.21`. Where `[COMMIT#]` is the commit of the PR that you merged
in `main`.
Note: Depending on workload and available bandwidth, one of the Knative
team members might be able to help handle the `git cherry-pick` in order
to push the fix into the affected release branch(es).
See a list of the available documentation versions in the
[branches page](https://github.com/knative/docs/branches) of the `knative/docs`
repo.

116
help/contributor/how-to/styleguide.md Normal file
View File

@ -0,0 +1,116 @@
---
title: "Style guide"
linkTitle: ""
weight: 30
type: "docs"
---
All content accepted into the Knative documentation must be **clear** and
**understandable**. Generally, content should aim to be "task oriented" and
thorough.
The standard we use to make that determination is defined by
the [Google Developer Documentation Style
Guide](https://developers.google.com/style/).
**Start here**:
1. [Highlights](https://developers.google.com/style/highlights)
2. [General principles](https://developers.google.com/style/tone)
3. Use the sections below as reference.
## Use sentence case for titles and headings
Use sentence case for all titles and headings. Only capitalize the first
word of the heading, except for proper nouns or acronyms.
|Do | Don't
|--------------------|-----
|Configuring feature | Configuring Feature
|Using feature. | Using Feature
|Using HTTPS | Using https
## Use present tense
|Do | Don't
|-----------------------------|------
|This command starts a proxy. | This command will start a proxy.
Exception: Use future or past tense if it is required to convey the correct
meaning. This exception is extremely rare and should be avoided.
## 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.
## Use simple and direct language
Use simple and direct language. Avoid using unnecessary phrases, such as saying
"please."
|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.
## Address the reader as "you"
|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 ...
## Create useful links
There are good hyperlinks, and bad hyperlinks. The common practice of calling
links *here* or *click here* are examples of bad hyperlinks. Check out [this
excellent article](https://medium.com/@heyoka/dont-use-click-here-f32f445d1021)
explaining what makes a good hyperlink and try to keep these guidelines in
mind when creating or reviewing site content.
## 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.
|Do | Don't
|------------------------------------------|------
|Version 1.4 includes ... | In version 1.4, we have added ...
|Knative 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.
## Avoid jargon and idioms
Some readers speak English as a second language. Avoid jargon and idioms to help
make their understanding easier.
|Do | Don't
|----------------------|------
|Internally, ... | Under the hood, ...
|Create a new cluster. | Turn up a new cluster.
|Initially, ... | Out of the box, ...
## Avoid statements about the future
Avoid making promises or giving hints about the future. If you need to talk
about a feature in development, add a boilerplate under the front matter that
identifies the information accordingly.
### Avoid statements that will soon be out of date
Avoid using wording that becomes outdated quickly like "currently" and
"new". A feature that is new today is not new for long.
|Do | Don't
|------------------------------------|------
|In version 1.4, ... | In the current version, ...
|The Federation feature provides ... | The new Federation feature provides ...
## Other related items
* [Page formatting standards](./formatting.md)
* [Include dynamic content with shortcodes](./shortcodes.md)

65
help/contributor/new-blog/_index.md Normal file
View File

@ -0,0 +1,65 @@
---
title: "Creating blog posts"
linkTitle: "New blog post"
weight: 30
type: "docs"
showlandingtoc: "false"
---
The Knative blog is owned by the [Documentation working group](https://knative.dev/community/contributing/working-groups/working-groups/#documentation) and run by the [Editorial Team](#leadership).
This section covers documentation, processes, and roles for the [Knative blog](https://knative.dev/blog/).
## Leadership
- **Technical Editors:** [Lionel Villard](https://github.com/lionelvillard), [Evan Anderson](https://github.com/evankanderson)
- **Copy Editors:** [Ashleigh Brennan](https://github.com/abrennan89), [Caroline Lee](https://github.com/carieshmarie), [María Cruz](https://github.com/macruzbar)
- **Blog Community Managers:** [María Cruz](https://github.com/macruzbar), [Jonatas Baldin](https://github.com/jonatasbaldin)
## Contact
- Slack: [#docs](https://knative.slack.com/archives/C9CV04DNJ)
## Submit a Post
Anyone can write a blog post and submit it for review. Commercial content is not allowed. Please refer to the [blog guidelines](#blog-guidelines) for more guidance.
To submit a blog post, follow the steps below.
1. [Sign the Contributor License Agreements](https://github.com/knative/community/blob/main/CONTRIBUTING.md#contributor-license-agreements) if you have not yet done so.
1. Familiarize yourself with the Markdown format for existing blog posts in the [docs repository](https://github.com/knative/docs/tree/main/blog). Blog posts are categorized into different directories. You can explore the directories to find examples.
1. Write your blog post in a text editor of your choice.
1. (Optional) If you need help with markdown, check out [StakEdit](https://stackedit.io/app#) or read [GitHub's formatting syntax](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax) for more information.
1. Choose a directory in the [docs repository](https://github.com/knative/docs/tree/main/blog), and click **Create new file**.
1. Paste your content into the editor and save it. Name the file in the following way: *[BLOG] Your proposed title* , 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 on which the blog will be published.
1. When you save the file, GitHub will walk you through the pull request (PR) process.
1. A reviewer is assigned to all pull requests automatically. The reviewer checks your submission, and works with you on feedback and final details. When the pull request is approved, the blog will be scheduled for publication.
1. Ping editorial team members on Slack [#docs](https://knative.slack.com/archives/C9CV04DNJ) channel with a link to your recently created PR.
### Blog Guidelines
#### Suitable content:
- **Original content only**
- Knative [new feature releases and project updates](#communicating-new-project-releases)
- Tutorials and demos [start a blog](./blog-page.md)
- Use cases
- Content that is specific to a vendor or platform about Knative installation and use
#### Unsuitable Content:
- Blogs that do not address Knative in any way
- Content that doesn't interact with Knative APIs or interfaces
- Vendor pitches
## Communicating new project releases
**Scheduled releases:** The Knative project has a release every 6 weeks, and we need your help communicating new changes to our community! If you would like to contribute a blog post to the Knative blog, please consider writing about the latest changes to the project. Ideally, there should be a single blog post for every release version, for example, 0.17; 0.18; 0.19. The title convention should be: *Version [version number] release - [date]*. Release blog contributors should write a summary of the changes and select up to 3 highlights of the current release to write about.
**Big changes to the project.** Big changes to the project require a deep dive blog that describes the new feature in detail and give examples of the new functionality.
## Review Process
After a blog post is submitted as a PR, it is automatically assigned to a reviewer.
Each blog post requires a `lgtm` label from at least one person in the editorial team. Once the necessary labels are in place, one of the reviewers will add an `approved` label, and schedule publication of the blog post.
### Service level agreement (SLA)
Blog posts can take up to **1 week** to review. If you'd like to request an expedited review, please say so on your message when you ping the editorial team on Slack.

10
help/contributor/new-blog/blog-page.md Normal file
View File

@ -0,0 +1,10 @@
---
linkTitle: "Blog template"
weight: "30"
type: "docs"
aliases:
- "/template-blog-page"
- "/help/contributor/templates/template-blog-page"
---
{{% readfile file="/template-blog-entry.md" markdown="true" %}}

194
help/contributor/new-docs/_index.md Normal file
View File

@ -0,0 +1,194 @@
---
title: "Adding new documentation"
linkTitle: "New docs"
weight: 20
type: "docs"
showlandingtoc: "false"
---
To contribute new documentation, follow these steps:
1. Identify the audience and intended use for the information.
1. Choose the [type of content](#content-types) you wish to contribute.
1. You can use a template to get started:
* [New docs file](./docs-page.md)
* [New `_index.md` file](./index-page.md)
1. [Choose appropriate titles and filenames](#choosing-titles-and-filenames).
1. Write your new content. See the [How-to guides](/help/contributor/how-to/)
to help you with this process. Feel free to reach out to the
[Docs Working Group](/help/contributor/gettingstarted.md#get-help-from-the-community)
with any questions.
1. Open a PR in the [knative/docs GitHub repository](https://github.com/knative/docs)
to kick off the review process. For details, see our
[Using GitHub help](/help/contributor/how-to/github/#prs).
## Identify the audience and intended use
The best documentation starts by knowing the intended readers, their knowledge,
and what you expect them to do with the information. Otherwise, you cannot
determine the appropriate scope and depth of information to provide, its ideal
structure, or the necessary supporting information. The following examples show
this principle in action:
- The reader needs to perform a specific task: Tell them how to recognize when
the task is necessary and provide the task itself as a list of numbered steps,
don’t simply describe the task in general terms.
- The reader must understand a concept before they can perform a task: Before
the task, tell them about the prerequisite information and provide a link to
it.
- The reader needs to make a decision: Provide the conceptual information
necessary to know when to make the decision, the available options, and when
to choose one option instead of the other.
- The reader is an administrator but not a SWE: Provide a script,
not a link to a code sample in a developer’s guide.
- The reader needs to extend the features of the product: Provide an example of
how to extend the feature, using a simplified scenario for illustration
purposes.
- The reader needs to understand complex feature relationships: Provide a
diagram showing the relationships, rather than writing multiple pages of
content that is tedious to read and understand.
The most important thing to avoid is the common mistake of simply
giving readers all the information you have, because you are unsure about
what information they need.
If you need help identifying the audience for you content, we are happy to help
and answer all your questions during the [Docs Working Group](https://github.com/knative/community/blob/main/working-groups/WORKING-GROUPS.md)
biweekly meetings.
## Content types
When you understand the audience and the intended use for the information you
provide, you can choose content type that best addresses their needs. To make it
easy for you to choose, the following table shows the supported content types,
their intended audiences, and the goals each type strives to achieve:
<table>
<thead>
<tr>
<th>Content type</th>
<th>Goals</th>
<th>Audiences</th>
</tr>
</thead>
<tr>
<td>Concepts</td>
<td>Explain some significant aspect of Knative. For example, a concept page
describes the configuration model of a feature and explains its functionality.
Concept pages don't include sequences of steps. Instead, provide links to
corresponding tasks.</td>
<td>Readers that want to understand how features work with only basic
knowledge of the project.</td>
</tr>
<tr>
<td>Reference pages</td>
<td>Provide exhaustive and detailed technical information. Common examples
include API parameters, command-line options, configuration settings, and
advanced procedures. Reference content is generated from the Knative code
base and tested for accuracy.
</td>
<td>Readers with advanced and deep technical knowledge of the project that
needs specific bits of information to complete advanced tasks.</td>
</tr>
<tr>
<td>Examples</td>
<td>Describe a working and stand-alone example that highlights a set of
features, an integration of Knative with other projects, or an end-to-end
solution for a use case. Examples must use an existing Knative setup as a
starting point. Examples must include an automated test since they are maintained for technical accuracy.
</td>
<td>Readers that want to quickly run the example themselves and
experiment. Ideally, readers should be able to easily change the example
to produce their own solutions.</td>
</tr>
<tr>
<td>Tasks</td>
<td>Shows how to achieve a single goal using Knative features. Tasks contain procedures written
as a sequence of steps. Tasks provide minimal
explanation of the features, but include links to the concepts that
provide the related background and knowledge. Tasks must include automated
tests since they are tested and maintained for technical accuracy.</td>
<td>Readers that want to use Knative features.</td>
</tr>
<tr>
<td>Setup pages</td>
<td>Focus on the installation steps needed to complete an Knative
deployment. Setup pages must include automated tests since they are tested and maintained for technical accuracy.
</td>
<td>New and existing Knative users that want to complete a deployment.</td>
</tr>
<tr>
<td>Blog posts</td>
<td>
Focus on Knative or products and technologies related to it. Blog posts fall in one of the following three categories:
<ul>
<li>Posts detailing the author’s experience using and configuring Knative, especially those that articulate a novel experience or perspective.</li>
<li>Posts highlighting Knative features.</li>
<li>Posts detailing how to accomplish a task or fulfill a specific use case using Knative. Unlike Tasks and Examples, the technical accuracy of blog posts is not maintained and tested after publication.</li>
</ul>
</td>
<td>Readers with a basic understanding of the project who want to learn
about it in an anecdotal, experiential, and more informal way.</td>
</tr>
<tr>
<td>News entries</td>
<td>
Focus on timely information about Knative and related events. News entries typically announce new releases or upcoming events.
</td>
<td>Readers that want to quickly learn what's new and what's happening in
the Knative community.</td>
</tr>
<tr>
<td>FAQ entries</td>
<td>
Provide quick answers to common questions. Answers don't introduce any
concepts. Instead, they provide practical advice or insights. Answers
must link to tasks, concepts, or examples in the documentation for readers to learn more.
</td>
<td>Readers with specific questions who are looking for brief answers and
resources to learn more.</td>
</tr>
<tr>
<td>Operation guides</td>
<td>
Focus on practical solutions that address specific problems encountered while running Knative in a real-world setting.
</td>
<td>Service mesh operators that want to fix problems or implement
solutions for running Knative deployments.</td>
</tr>
</table>
## Choosing titles and filenames
Choose a title for your new content, either a new page title or a title for
a section that you want to add. Make sure it includes the keywords you want
search engines to find and use sentence style capitalization.
#### New files
The filename of your new content should reflect that the title.
#### New files and folders
If the content that you add include a new folder, name that folder using
the keywords that cover the scope of the content in the folder, separated by
hyphens, all in lowercase. Keep folder names as short as possible to make
cross-references easier to create and maintain. You should only need to create
a new folder if you are adding multiple topics/files, or if you are grouping
related content. The names for each file do not need to repeat the folder name
since that context is already established.
For more guidance, see the
[Headings and titles](https://developers.google.com/style/headings) section in
the style guide.
## Submit your contribution to GitHub
If you are not familiar with GitHub, see our [working with GitHub guide](../how-to/github.md)
to learn how to submit documentation changes.

10
help/contributor/new-docs/docs-page.md Normal file
View File

@ -0,0 +1,10 @@
---
linkTitle: "Docs template"
weight: "10"
type: "docs"
aliases:
- "/template-docs-page"
- "/help/contributor/templates/template-docs-page"
---
{{% readfile file="/template-docs-page.md" markdown="true" %}}

10
help/contributor/new-docs/index-page.md Normal file
View File

@ -0,0 +1,10 @@
---
linkTitle: "_index.md template"
weight: "50"
type: "docs"
aliases:
- "/template-_index-page"
- "/help/contributor/new-docs/template-_index-page"
---
{{% readfile file="/template-_index-page.md" markdown="true" %}}

187
help/contributor/publishing.md Normal file
View File

@ -0,0 +1,187 @@
---
title: "Staging and publishing Knative documentation"
linkTitle: "Website help"
weight: "60"
type: "docs"
---
## Testing your documentation
Before you kick off a PR review you can verify that:
- The page and any elements like widgets, titles, and links, work and
renders correctly.
- If you moved or deleted a page, make sure to test that the redirects
(`aliases`) all work.
### Auto PR preview builds
All PRs are automatically built and a Preview is generated at:
https://app.netlify.com/sites/knative/deploys
This is currently a manual process.
1. Navigate to https://app.netlify.com/sites/knative/deploys
1. Click to view a build log. The list of build logs are ordered from
most recent to oldest. If you just pushed to your PR, then that build log is
near the top.
1. Scroll down to see the `PR#` in the log and verify that it's for your PR.
1. When you find the build log for your PR, click the **[Preview]** button to
view the unique build preview for your PR.
**Important**: Each "event" in a Knative PR triggers a new/unique build
(Preview). Therefore, if you push a new commit, a new build with those
changes will appear at the top of https://app.netlify.com/sites/knative/deploys.
### Local preview builds
You can run a local preview of you fork. See the following setup section for
details about installing the required software.
- Current supported Hugo version https://github.com/knative/website/blob/main/netlify.toml
- How to build knative.dev locally: Run [`https://github.com/knative/website/blob/main/scripts/localbuild.sh`](https://github.com/knative/website/blob/main/scripts/localbuild.sh)
#### Setup the local requirements
1. Clone this repo (or your fork) using `--recurse-submodules`, like so:
```shell
git clone --recurse-submodules https://github.com/knative/website.git
```
If you accidentally cloned this repo without `--recurse-submodules`, you'll
need to do the following inside the repo:
```shell
git submodule init
git submodule update
cd themes/docsy
git submodule init
git submodule update
```
(Docsy uses two submodules, but those don't use further submodules.)
1. Clone the docs repo next to (_not inside_) the website repo. This allows you
to test docs changes alongside the website:
```shell
git clone https://github.com/knative/docs.git
```
You may also want to clone the community repo:
```shell
git clone https://github.com/knative/community.git
```
1. (Optional) If you want to change the CSS, install
[PostCSS](https://www.docsy.dev/docs/getting-started/#install-postcss)
1. Install a supported version of [Hugo](https://www.docsy.dev/docs/getting-started/#install-hugo).
#### Run locally
You can use `./scripts/localbuild.sh` to build and test files locally.
The script uses Hugo's build and server commands in addition to some Knative
specific file scripts that enables optimal user experience in GitHub
(ie. use README.md files, allows our site to use relative linking
(not
[`rel` or `relref`](https://gohugo.io/content-management/cross-references/#use-ref-and-relref)),
etc.) and also meets Hugo/Docsy static site generator
and template requirements (ie. _index.hmtl files, etc.)
The two local docs build options:
- Simple/static HTML file generation for viewing how your Markdown renders in HTML:
Use this to generate a static build of the documentation site into HTML. This
uses Hugo's build command [`hugo`](https://gohugo.io/commands/hugo/).
From your clone of knative/website, you run `./scripts/localbuild.sh`.
All of the HTML files are built into the `public/` folder from where you can open,
view, and test how each file renders.
Notes:
- This method does not mirror how knative.dev is generated and therefore is
only recommend to for testing how your files render. That also means that link
checking might not be 100% accurate. Hugo builds relative links differently
(all links based on the site root vs relative to the file in which the link
resides - this is part of the Knative specific file processing that is done)
therefore some links will not work between the statically built HTML files.
For example, links like `.../index.html` are converted to `.../` for simplicity
(servers treat them as the same destination) but when you are browsing a local HTML
file you need to open/click on the individual `index.html` files to get where you want
to go.
- This method does however make it easier to read or use local tools on the HTML build
output files (vs. fetching the HTML from the server). For example, it is useful for
refactoring/moving content and ensuring that complicated Markdown renders properly.
- Using this method also avoids the MacOs specific issue (see below), where the default
open FD limit exceeds the total number of `inotify` calls that Hugo wants to keep open.
- Mimic how knative.dev is built and hosted:
Use this option to locally build knative.dev. This uses Hugo's local server
command [`hugo server`](https://gohugo.io/commands/hugo_server/).
From your clone of knative/website, you run `./scripts/localbuild.sh -s true`.
All of the HTML files are temporarily copied into the `content/en/` folder to allow
the Hugo server to locally host those files at the URL:port specified in your terminal.
Notes:
- This method provides the following local build and test build options:
- test your locally cloned files
- build and test other user's remote forks (ie. locally build their PRs `./scripts/build.sh -f repofork -b branchname -s`)
- option to build only a specific branch or all branches (and also from any speicifed fork)
- fully functioning site links
- [See all command options in localbuild.sh](https://github.com/knative/website/blob/main/scripts/localbuild.sh)
- Hugo's live-reload is not completely utilized due to the required Knative specific file processing
scripts (you need to rerun `./scripts/localbuild.sh -s` to rebuild and reprocess any changes that you
make to the files from within your local knative/docs clone directory).
Alternatively, if you want to use Hugo's live-reload feature, you can make temporary
changes to the copied files within the `content/en/` folder, and then when satisfied, you must
copy those changes into the corresponding files of your knative/docs clone.
- Files in `content/en/` are overwritten with a new copy of your local files in your knative/docs
clone folder each time that you run this script. Note that the last set of built files remain
in `content/en/` for you to run local tools against but are overwritten each time that you rerun the script.
- Using this method causes the MacOs specific issue (see below), where the default
open FD limit exceeds the total number of `inotify` calls that the Hugo server wants to keep open.
## On a Mac
If you want to develop on a Mac, you'll find two obstacles:
### Sed
The scripts assume GNU `sed`. You can install this with
[Homebrew](https://brew.sh/):
```shell
brew install gnu-sed
# You need to put it in your PATH before the built-in Mac sed
PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"
```
### File Descriptors in "server mode"
By default, MacOS permits a very small number of open FDs. This will manifest
as:
```
ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files
```
You can fix this with the following (may be needed for each new shell):
```shell
sudo launchctl limit maxfiles 65535 200000
# Probably only need around 4k FDs, but 64k is defensive...
ulimit -n 65535
sudo sysctl -w kern.maxfiles=100000
sudo sysctl -w kern.maxfilesperproc=65535
```

26
help/faqs.md Normal file
View File

@ -0,0 +1,26 @@
---
title: "FAQs and troubleshooting"
linkTitle: "FAQs"
weight: "100"
type: "docs"
---
A collection of FAQs from other docs contributors.
### Common GitHub PRs FAQs
1. The CLA check fails even though you have signed the CLA. This may occur if
you accept and commit suggestions in a pull request from another person's
account, because the email address of that account doesn't match the address
on record for the CLA. The commit will show up as co-authored, which can
cause issues if your public email address has not signed the CLA.
1. One or more tests are failing. If you do not see a specific error related to
a change you made, and instead the errors are related to timeouts, try
rerunning the test at a later time. There are running tasks that could result
in timeouts or rate limiting if your test runs at the same time.
### General troubleshooting
1. Other Issues/Unsure - reach out in the #docs Slack channel and someone will
be happy to help out.

7
help/maintainer/_index.md Normal file
View File

@ -0,0 +1,7 @@
---
title: "How-to guides for maintainers of the Knative docs repo"
linkTitle: "Maintainer guides"
weight: 50
type: "docs"
showlandingtoc: "true"
---

138
help/maintainer/building-api-output.md Normal file
View File

@ -0,0 +1,138 @@
---
title: "Building API docs from the Knative component repos"
linkTitle: "Generating API docs"
weight: 85
type: "docs"
---
The Knative API docs are built from the code in the Knative
[Serving](https://github.com/knative/serving/) and
[Eventing](https://github.com/knative/eventing/) repos.
New API docs are generated and then published at
https://www.knative.dev/docs/reference/api for every release.
### Source files
API source files are located at:
- [Serving API](../../../reference/api/serving.md)
- [Eventing API](../../../reference/api/eventing/eventing.md)
## Updating API Reference docs (for Knative maintainers)
The Knative API reference documentation is manually generated using the
[`gen-api-reference-docs.sh`](../../../hack/) tool. If you need to generate a new
version of the API docs for a recent update or for a new release, you can use
the following steps.
To learn more about the tool, see the
[gen-crd-api-reference-docs](https://github.com/ahmetb/gen-crd-api-reference-docs)
reference page.
### Before you begin
You must meet the following requirements to run the `gen-api-reference-docs.sh`
tool:
- You need the following software installed:
- [`git`](https://git-scm.com/download/)
- [`go` version 1.11+](https://golang.org/dl/)
- Clone [knative/docs](https://github.com/knative/docs) locally. For example:
`git clone git@github.com:knative/docs.git`
### Generating the API
To generate a version of the API:
1. Ensure that your `GOPATH` is empty. The `gen-api-reference-docs.sh` script
will result in the `GOPATH should not be set` error if your `GOPATH` is
configured. You view the value by running the following command:
```
echo $GOPATH
```
If your `GOPATH` is already configured, temporarily clear the `GOPATH` value
by running the following command:
```
export GOPATH=""
```
1. Locate the commits or tags that correspond to the version of the API that you
want to generate:
- [Serving](https://github.com/knative/serving/releases/)
- [Eventing](https://github.com/knative/eventing/releases/)
1. To run the `gen-api-reference-docs.sh` command from the `hack` directory, you
specify the commits or tags for each of the corresponding Knative component
variables (`KNATIVE_[component_name]_COMMIT`):
```
cd hack
KNATIVE_SERVING_COMMIT=[commit_or_tag] \
KNATIVE_EVENTING_COMMIT=[commit_or_tag] \
./gen-api-reference-docs.sh
```
where `[commit_or_tag]` is the commit or tag in the specific repo that
represents the version of the API that you want to generate. Also see the
[example](#example) below.
**Result**
The `gen-api-reference-docs.sh` tool generates the API in a `tmp` folder.
After a successful build, the tool automatically opens that folder in the
`tmp` directory.
If the script fails, there are a couple possible causes.
* If you get the
`F1116 15:21:23.549503 63473 main.go:129] no API packages found in ./pkg/apis`
error, check if a new version of the script is available:
https://github.com/ahmetb/gen-crd-api-reference-docs/tags
The script is kept up-to-date with changes that go into the Kubernetes API.
As Knative adds support for those APIs, you might need to make sure the
corresponding
[script `gen-crd-api-reference-docs` version](https://github.com/knative/docs/blob/main/hack/gen-api-reference-docs.sh#L26)
is used.
* If you get the
`F0807 13:58:20.621526 168834 main.go:444] type invalid type has kind=Unsupported which is unhandled`
error, the import target might have moved. There might be other causes for
that error but view [#2054](https://github.com/knative/docs/pull/2054)
(and the linked Issues) for details about how we handled that error
in the past.
1. Copy the generated API files into the `docs/reference` directory of your
knative/docs clone.
1. The linter now fails for content with trailing whitespaces. Use a tool of
your choice to remove all trailing whitespace. For example, search for and
remove: `\s+$`
You can now perform the necessary steps to open a PR, complete a review, and
merge the new API files into the appropriate branch of the `knative/docs` repo.
See the [contributor flow](https://github.com/knative/community/blob/main/docs/DOCS-CONTRIBUTING.md) for details
about requesting changes in the `knative/docs` repo.
### Example
To build a set of Knative API docs for v0.18, you can use the `v0.18.0` the tags
from each of the Knative component repositories, like
[Serving v0.18.0](https://github.com/knative/serving/tree/v0.18.0). If you want to
use a commit for Serving v0.18.0, you would use
[850b7c](https://github.com/knative/serving/commit/850b7cca7d7701b052420a030f2308d19938d45e).
Using tags from each repo, you would run the following command to generate the
v0.18.0 API source files:
```
KNATIVE_SERVING_COMMIT=v0.18.0 \
KNATIVE_EVENTING_COMMIT=v0.18.0 \
./gen-api-reference-docs.sh
```

147
help/maintainer/docs-release-process.md Normal file
View File

@ -0,0 +1,147 @@
---
title: "Releasing a version of the Knative documentation"
linkTitle: "Release process"
weight: 75
type: "docs"
---
Learn how to promote the current in-development version of the knative/docs
repo (`main`), to a released version by creating a dedicated `release-#.#`
branch and corresponding section knative.dev.
## Before you begin
* For updating and building website on knative.dev
* Be granted access to Netlify for staging
* Contact Caroline Lee or Richie Escarez
* For GitHub
* [Set up keys for SSH access](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh)
* [Configure two remote repos](https://articles.assembla.com/en/articles/1136998-how-to-add-a-new-remote-to-your-git-repo) for your local /docs and /website clones:
* "origin" - pointed at main repo (git@github.com:knative/docs.git)
* "upstream" - pointed at your fork of main repo (git@github.com:<your fork>/docs.git)
* For building website locally:
* [Install Hugo](https://www.docsy.dev/docs/getting-started/#install-hugo)
* (for Mac) Install gnu-sed using brew: brew install gnu-sed
* Update path to gnu-sed: `PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"`
* [Go version 1.11+](https://golang.org/dl/)
* Clone git@github.com:knative/website.git (has build script)
* To create combined PRs.
Make your first pull request, choose Create a new branch. Give it a name you will remember.
Then when you make your subsequent updates, make sure you select the branch you just created so you can add all your
changes to the same PR.
## Check Eventing and Serving
Have they created related release branches?
https://github.com/knative/<repo-name>/releases/
## Create matching branch for Knative docs
Once there are release branches for the three code repos, make a matching doc repo release.
### Prepare the 'main' branch
Make sure main is in correct state:
* [Generate the latest set of API reference docs](https://github.com/knative/docs/tree/main/docs/reference#updating-api-reference-docs-for-knative-maintainers) locally
* Clone the docs repo: git clone git@github.com:knative/docs.git
* Find the gen-api-reference-docs.sh script in the /docs/hack directory
* Follow the instructions in the linked doc above. This creates a small set of files that document the APIs in this
release. Be aware that if there have been significant changes, the script may take hours to run to completion.
* Push to your personal GitHub repository.
* Create a PR and check into the Knative main repository.
* At this point the updated versions of the API docs are in knative/docs main
* Check to make sure all changes, including install changes, have been merged into main and all hard-coded version numbers are updated. This is to make sure that any docs that have been committed outside of the normal process don't have mechanical errors in them. This is, alas, a manual step.
### Create branch from updated main
Once everything that needs to be in main is in main you need to create the release branch, using the GitHub UI.
1. Make sure you are logged into GitHub.
2. Select the Code tab in the Knative/docs repo.
3. Click and open the Branch drop-down menu. Make sure that main is selected. This is the source for the new release.
4. In the Find or create a branch text field, enter the name of the new branch you want to create: release-#.#
![branch](https://user-images.githubusercontent.com/35748459/87461583-804c4c80-c5c3-11ea-8105-f9b34988c9af.png)
The branch is created.
### Update links
Make sure all links in new release branch announcement point to the appropriate peer Knative repos
* Update all hard coded URLs to repos from "tree/main" to "tree/release-0.#"
* For Serving, Eventing, and Eventing-contrib
### Demote the previous release to archive
* Remove the "aliases" field from the frontmatter of files from the previous release so that they look like this:
title: "Knative contribution guidelines"
linkTitle: "Contributing"
weight: 20
type: "docs"
Or
* Change the "aliases" field to point to the archived version file so "/docs/<the file name>/" becomes "/<the archived version>-docs/<the file name>/":
title: "Knative contribution guidelines"
linkTitle: "Contributing"
weight: 20
type: "docs"
aliases:
/v0.9-docs/contribution-guidelines/
Not all files will have aliases on them. You just have to go through them manually. Update one, create a branch for your pull request, then update all of the others using that branch, by committing to that branch. Then create one pull request for all the changes. **Make sure you make the pull request against the branch you are archiving,** ie, the one before the one you just made.
## Complete the release announcement and create the tag
### Link all the release notes together
* On https://github.com/knative/docs/releases, click Draft a new release.
![release-notes](https://user-images.githubusercontent.com/35748459/87462834-61e75080-c5c5-11ea-83ec-94c556255db8.png)
![tags](https://user-images.githubusercontent.com/35748459/87462941-8e9b6800-c5c5-11ea-951b-2bacdb4061ec.png)
* Using the box in red above, create a tag with the release (v.0.<number>.x). Copy the text of the source content from the previous release, updating the number and linking to the appropriate release notes in each of the three components.
* Check **Pre-release**
* Click **Publish release** (or **Save draft** if you are not ready to finalize).
## Configure the /website build
Update the build configuration to include the new version and remove the oldest by editing the following .toml (Tom's Obvious, Minimal Language) files. Tom's files aren't really obvious, but tastes vary. There are also some traditional script files. Use the github UI In the /website main branch. Click the link to go to the page to edit and insert the appropriate
values:
* Configure defaults: [/website/config/_default/params.toml](https://github.com/knative/website/blob/main/config/_default/params.toml)
This lets the build know what the "default" release is. Add the release version you just created.
![default](https://user-images.githubusercontent.com/35748459/87463577-81cb4400-c5c6-11ea-8a69-3023b07adba0.png)
* Configure production builds: [/website/confi/production/params.toml]( https://github.com/knative/website/blob/main/config/production/params.toml)
We build four versions of the docs every time - the version you just created, and the previous three versions.
Set the version on line 41 to the version you just created. Set the "Archived versions" to the three previous versions.
Remove any older versions.
![production](https://user-images.githubusercontent.com/35748459/87464225-9cea8380-c5c7-11ea-8f31-fe7872cad81d.png)
* Configure local builds: [/website/config/local/params.toml]()
This is really just for builds you do on your machine, but update it on github as well to keep everything in sync. Set line 20
to the version you just created.
![local](https://user-images.githubusercontent.com/35748459/87464508-13878100-c5c8-11ea-840f-25e4ab80e372.png)
* Configure staging builds: [/website/config/staging/params.toml](https://github.com/knative/website/blob/main/config/staging/params.toml)
Set line 19 to the version you just created.
![staging](https://user-images.githubusercontent.com/35748459/87464866-afb18800-c5c8-11ea-9ce0-74331523d651.png)
* Define the default branch variable:[/website/scripts/docs-version-settings.sh](https://github.com/knative/website/blob/main/scripts/processsourcefiles.sh)
This variable should be set to the version you just created.
![doc-version](https://user-images.githubusercontent.com/35748459/87465326-4bdb8f00-c5c9-11ea-95c7-8a9e3b8abecd.png)
* Tell Netlify how to get the previous three releases by updating the three git clone commands to point to those three releases: [/website/scripts/processsourcefiles.sh](https://github.com/knative/website/blob/main/scripts/processsourcefiles.sh)
![processsource](https://user-images.githubusercontent.com/35748459/87465528-ad9bf900-c5c9-11ea-8364-d391c1926332.png)
* Add the just created version to line 24 of the Netlify toml file. The :splat keeps the links to the three previous versions
alive, so the current version + the previous 3 versions that are still being built. The bottom release that fell out of the top
four should be added to the redirects below line 29. Any links to these versions are redirected back to the most current
version: [/website/netlify.toml](https://github.com/knative/website/blob/main/netlify.toml)
![netlify](https://user-images.githubusercontent.com/35748459/87465963-54809500-c5ca-11ea-8372-3fbcfc965e20.png)
## Test the content
* Update your local versions of the build config files to run a local build.
* Run a local build using from the /website directory: scripts/localbuild.sh. Follow the extensive instructions at the top of the script file.
* Check to make sure everything looks okay.
* Sync your changes to the staging branch with git pull --rebase upstream main and git push upstream staging. {need more detail}
## Check the staging (Deploy Preview) build on Netlify
* Go to [https://app.netlify.com/sites/knative/deploys]( https://app.netlify.com/sites/knative/deploys
)
![Deploys](https://user-images.githubusercontent.com/35748459/87466537-44b58080-c5cb-11ea-9b0e-6f14679dbede.png)

118
help/maintainer/docs-repo-maintanence.md Normal file
View File

@ -0,0 +1,118 @@
---
title: "Maintaining the Knative doc and website repos"
linkTitle: "Repo maintenance"
weight: 100
type: "docs"
---
## How GitHub and Netlify are hooked up
https://knative.dev/ is built and served by [Netlify](https://netlify.com/) on their platform.
When debugging issues on the website, it can be useful to understand what Netlify is doing (as we've
configured it).
Generally, Netlify runs Hugo/Docsy builds and publishes everything that gets merged into the knative/docs and knative/website repos
(anything in knative/community will get picked up when either of the other two repos trigger a build).
The builds are triggered are through [GitHub webhooks](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads).
There are two webhooks sent from knative/docs that are configured to inidicate that they were sent from knative/website:
* One that triggers a "production" build - Any PR that gets merged. (Webhook payload - /website `main` branch)
* One that triggers a "preview" build - Any PR action other than a merge (ie. commit, comment, label, etc). (Webhook payload - /website `staging` branch)
All of our builds (and build logs) are shown here: https://app.netlify.com/sites/knative/deploys (in the order of recent to past)
## Keep knative/website 'staging' with 'main' in sync
Both branches are identical but all PRs get merged into `main`. They can drift
apart since staging only builds the PR owners fork and branch. It's best to keep
in sync to avoid dealing with merge conflicts.
Two branches are used only to align with and use Netlify's built-in continuous
site deployment configuration:
`main` - triggered when any PR gets pushed into knative/docs
`staging` - triggered for any event (other than 'push') in a PR
Assuming that you have a local fork of the knative/website `staging` branch:
1. Copy `main` into `staging`, for example:
* Merge:
```
git checkout staging
git pull upstream main
git push origin staging
```
* Hard reset and force push also works:
```
git checkout staging
git reset --hard upstream/main
git push -f origin staging
```
1. Open a PR and merge into knative/website staging
## Check for and keep Hugo and Docsy up-to-date:
- Hugo releases: Update local versions if you use scripts/localbuild.sh. Update https://github.com/knative/website/blob/main/netlify.toml#L5
- Docsy releases: https://www.docsy.dev/docs/updating/
## Other notes
- How to hide files from the build: https://github.com/knative/website/blob/main/config/_default/config.toml#L12
Account info (include current owners):
- Netlify
- Google Domains
- Google Analytics
- Google Search
### Website infrastructure:
- Hugo - static site engine
- Includes a version of Bootstrap
- Docsy - Hugo template for technical documentation
- [Markdown processor info](https://gohugo.io/getting-started/configuration-markup/)
- Netlify - continuous build
- GitHub repos
- knative/docs repo
- knative/website repo
- knative/community repo
### Integration tests
- Link checking
- Whitespace lint
## Todos
Other "docs contributor" related items:
- [ ] https://github.com/knative/docs/issues/1032
- [ ] https://github.com/knative/docs/issues/1009
- [ ] https://github.com/knative/docs/issues/1282
- [ ] https://github.com/knative/docs/issues/1239
- [ ] https://github.com/knative/docs/issues/1344
Recent items:
[ ] Auto PR staging: https://app.netlify.com/sites/knative/deploys
[ ] How Prow chooses reviewers: https://github.com/kubernetes/test-infra/tree/master/prow/plugins/approve/approvers#blunderbuss-selection-mechanism
[ ] GitHub troubleshooting: https://github.com/knative/docs/issues/2755
Build scripts:
- How cross linking between /docs and /community works

45
smoketest.md
View File

@ -1,7 +1,3 @@
# Spacer Title
<br><br>
# Hidden smoketest page
Use this page to test your changes and ensure that there are not any issues,
@ -29,9 +25,13 @@ Below are a set of site elements that have causes issues in the past.
The following use the
[`readfile` shortcode](https://github.com/knative/website/blob/main/layouts/shortcodes/readfile.md)
{{< readfile file="hack/reference-docs-gen-config.json" code="true" lang="json" >}}
Shortcode: <code>{<code>{< readfile file="./hack/reference-docs-gen-config.json" code="true" lang="json" >}</code>}</code>
renders as:
{{< readfile file="./hack/reference-docs-gen-config.json" code="true" lang="json" >}}
{{< readfile file="Gopkg.toml" code="true" lang="toml" >}}
Shortcode: <code>{<code>{< readfile file="./docs/serving/samples/cloudevents/cloudevents-nodejs/service.yaml" code="true" lang="yaml" >}</code>}</code>
renders as:
{{< readfile file="./docs/serving/samples/cloudevents/cloudevents-nodejs/service.yaml" code="true" lang="yaml" >}}
## Install version numbers and Clone branch commands
@ -41,43 +41,48 @@ added in-line with the
(uses the define values from
[config/\_default/params.toml](https://github.com/knative/website/blob/main/config/_default/params.toml))
1. Shortcode: <code>{<code>{% version %}</code>}</code>
1. Shortcode: <code>{<code>{< version >}</code>}</code>
renders as: {{< version >}}
Example:
`kubectl apply version/{{% version %}}/is-the-latest/docs-version.yaml`
`kubectl apply version/{{< version >}}/is-the-latest/docs-version.yaml`
1. Shortcode: <code>{<code>{% version override="v0.2.2" %}</code>}</code>
1. Shortcode: <code>{<code>{< version override="v0.2.2" >}</code>}</code>
renders as: {{< version override="v0.2.2" >}}
Example:
`kubectl apply the-version-override/{{% version override="v0.2.2" %}}/is-manually-specified.yaml`
`kubectl apply the-version-override/{{< version override="v0.2.2" >}}/is-manually-specified.yaml`
1. Shortcode: <code>{<code>{% version patch=".20" %}</code>}</code>
1. Shortcode: <code>{<code>{< version patch=".20" >}</code>}</code>
renders as: {{< version patch=".20" >}}
Example:
`kubectl apply this-is-a-point-release/{{% version patch=".20" %}}/filename.yaml`
`kubectl apply this-is-a-point-release/{{< version patch=".20" >}}/filename.yaml`
1. Shortcode: <code>{<code>{% branch %}</code>}</code>
1. Shortcode: <code>{<code>{< branch >}</code>}</code>
renders as: {{< branch >}}
Example:
`git clone -b "{{% branch %}}" https://github.com/knative/docs knative-docs`
`git clone -b "{{< branch >}}" https://github.com/knative/docs knative-docs`
1. Shortcode: <code>{<code>{% branch override="release-0.NEXT" %}</code>}</code>
1. Shortcode: <code>{<code>{< branch override="release-0.NEXT" >}</code>}</code>
renders as: {{< branch override="release-0.NEXT" >}}
Example:
`git clone -b "{{% branch override="release-0.NEXT" %}}" https://github.com/knative/docs knative-docs`
`git clone -b "{{< branch override="release-0.NEXT" >}}" https://github.com/knative/docs knative-docs`
## Tabs
How to include tabbed content in your page. Note that you can set a default tab.
(View the raw version of this page for example syntax; it doesn't render well here.)
[View this file in GitHub](https://github.com/knative/docs/blob/main/docs/smoketest.md)
{{< tabs name="tabs_example" default="Include example" >}}
{{% tab name="Regular example" %}}
{{< tab name="Regular example" >}}
This is a regular example tab.
{{< /tab >}}
{{% tab name="Include example" %}}
{{% readfile file="./docs/install/README.md" %}}
{{< tab name="Include example" >}}
{{% readfile file="./docs/serving/samples/multi-container/service.yaml" code="true" lang="yaml" %}}
{{< /tab >}}
{{< /tabs >}}

219
template-_index-page.md Normal file
View File

@ -0,0 +1,219 @@
# _index.md page template instructions
An example template with best-practices that you can use for creating a
new `_index.md` file.
Generally, you only need to create a `_index.md` file if are creating a new
folder that contains (or will contain) multiple pages. Best practice is to
avoid creating a folder that includes only a single page.
[Learn more about the `_index.md` file](https://gohugo.io/content-management/organization/#index-pages-_indexmd).
[**Copy a version of this template without the instructions**](#copy-the-template)
## Frontmatter
[Hugo](https://gohugo.io/) uses a set of metadata at the beginning of each page
called [frontmatter](https://gohugo.io/content-management/front-matter/)
to define website build required info as well as other blog page details.
Frontmatter is strict YAML syntax and must be added to the top of every
page. Example formatting template:
```yaml
---
title: ""
#linkTitle: ""
weight: 50
type: "docs"
showlandingtoc: "false"
---
```
```
<!--
# This section is called the "frontmatter" for your page that is defined in YAML.
---
title: ""
# The title of this page (renders at the top of the page). Use sentence case.
linkTitle: ""
# Optional: Use it to provide a shorter title for the page link so that it fits
# in the left navigation menu (to prevent wrapping)
weight: ""
# This specifies the vertical the placement of the page link in the left
# navigation menu. Pages are ordered from top (lowest weight) to bottom (highest weight).
type: "docs"
# You won't need to update this.
aliases:
- /docs/example/redirect/moved-renamed-page
- /docs/another-example
# Optional: Specifies a URL to redirect to this page.
# For example, has this page moved (are you replacing one or more deleted pages)?
# If yes, include the aliases frontmatter and specify the prior location of the
# page(s)/path(s) to redirect to this page. Specify the path and filename starting
# from the site root (for example /docs/, /blog/, or /community/).
showlandingtoc: "false"
# Required only in _index.md files
# Defaults to "true" and renders an in-page TOC of any/all the child pages in
# this section.
---
-->
```
```
<!-- The page title you set in the frontmatter renders here (don't add a duplicate title) -->
```
```
<!--
The content in _index.md files generally fall into two categories (but are not
limited to them).
- Use this page as a top level "landing page" that provides a high-level
introduction to all the info covered within this section.
- Use this page to introduce a large complex process that has multiple logical
tasks or options.
Examples:
- Use it to introduce large complex process, where each task of the process
is covered in separate pages. Structure:
- New-Folder
- _index.md (introduce process)
- before-you-begin-steps.md (prerequisites)
- process-step1.md
- process-step2.md
- process-results_cleanup_whatsnext.md
- Use it to introduce the multiple ways to accomplish the same task, where
each optional task is covered in separate
pages. Structure:
- New-Folder
- _index.md (introduce options)
- how-to-opt-1.md
- how-to-opt-2.md
- ...
-->
```
The following demonstrates a generic landing page. For more
information about stucturing a how-to guide, see the
[new page template instructions](./template-docs-page.md).
Learn how to do something very cool.
```
<!--
Make sure to state the goal of this section and the value proposition for the
user (why is this important?).
Example:
Learn how to use X to reduce/improve/etc. your Y and Z.
Generally, make sure you answer the questions:
- "what does this section show you how to do?"
- "why would someone want to do this?"
-->
```
You can set `showlandingtoc:` to `"true"` and dynamically render an in-page TOC
below the body of the text you add in this page.
# Copy the template
```yaml
---
title: ""
linkTitle: ""
weight: 50
type: "docs"
showlandingtoc: "false"
---
<!--
# This section is called the "frontmatter" for your page that is defined in YAML.
---
title: ""
# The title of this page (renders at the top of the page). Use sentence case.
linkTitle: ""
# Optional: Use it to provide a shorter title for the page link so that it fits
# in the left navigation menu (to prevent wrapping)
weight: ""
# This specifies the vertical the placement of the page link in the left
# navigation menu. Pages are ordered from top (lowest weight) to bottom (highest weight).
type: "docs"
# You won't need to update this.
aliases:
- /docs/example/redirect/moved-renamed-page
- /docs/another-example
# Optional: Specifies a URL to redirect to this page.
# For example, has this page moved (are you replacing one or more deleted pages)?
# If yes, include the aliases frontmatter and specify the prior location of the
# page(s)/path(s) to redirect to this page. Specify the path and filename starting
# from the site root (for example /docs/, /blog/, or /community/).
showlandingtoc: "false"
# Required only in _index.md files
# Defaults to "true" and renders an in-page TOC of any/all the child pages in
# this section.
---
-->
<!-- The page title you set in the frontmatter renders here (don't add a duplicate title) -->
<!--
The content in _index.md files generally fall into two categories (but are not
limited to them).
- Use this page as a top level "landing page" that provides a high-level
introduction to all the info covered within this section.
- Use this page to introduce a large complex process that has multiple logical
tasks or options.
Examples:
- Use it to introduce large complex process, where each task of the process
is covered in separate pages. Structure:
- New-Folder
- _index.md (introduce process)
- before-you-begin-steps.md (prerequisites)
- process-step1.md
- process-step2.md
- process-results_cleanup_whatsnext.md
- Use it to introduce the multiple ways to accomplish the same task, where
each optional task is covered in separate
pages. Structure:
- New-Folder
- _index.md (introduce options)
- how-to-opt-1.md
- how-to-opt-2.md
- ...
-->
<!--
The following demonstrates a generic landing page. For more
information about stucturing a how-to guide, see the
[new page template instructions](./template-docs-page.md).
-->
Learn how to do something very cool.
<!--
Make sure to state the goal of this section and the value proposition for the
user (why is this important?).
Example:
Learn how to use X to reduce/improve/etc. your Y and Z.
Generally, make sure you answer the questions:
- "what does this section show you how to do?"
- "why would someone want to do this?"
-->
<!--
You can set `showlandingtoc:` to `"true"` and dynamically render an in-page TOC
below the body of the text you add in this page.
-->
```

15
template-blog-entry.md
View File

@ -1,6 +1,7 @@
# Blog template instructions
An example template that you can use to start drafting an entry to post on the Knative blog.
An example template with best-practices that you can use to start drafting an
entry to post on the Knative blog.
[**Copy a version of this template without the instructions**](#copy-the-template)
@ -23,7 +24,7 @@ authorHandle: "" # Your GitHub ID
date: "" # Publishing date
description: "" # A short one-liner describing this blog entry
folderWithMediaFiles: "./images/<new-feature-name>" # The relative file path (ie. new folder) to any images, etc.
keywords: Releases, Steering committee, Demo, Events # Meta keywords for the content
keywords: "Releases, Steering committee, Demo, Events" # Meta keywords for the content
---
```
@ -105,10 +106,10 @@ title: ""
linkTitle: ""
author: ""
authorHandle: ""
date: "" # Publishing date
description: "" # A short one-liner describing this blog entry
folderWithMediaFiles: "./images/<new-feature-name>" # The relative file path (ie. new folder) to any images, etc.
keywords: Releases, Steering committee, Demo, Events # Meta keywords for the content
date: ""
description: ""
folderWithMediaFiles: ""
keywords: ""
---
<!--
@ -118,6 +119,8 @@ keywords: Releases, Steering committee, Demo, Events # Meta keywords for the con
| <!-- GitHub ID --> | YYYY-MM-DD | :+1:, :monocle_face:, :-1: |
-->
<!-- The page title you set in the frontmatter renders here (don't add a duplicate title) -->
## Blog content body
<!-- Introduce the feature you are going to explain:
* state what the goal of this blog entry is

106
template-docs-page.md
View File

@ -1,6 +1,11 @@
# Documentation template instructions
An example template that you can use to provide best-practices for starting a new how-to document.
An example template with best-practices that you can use to start drafting a new
how-to document.
Use this template if you are creating a new page in an existing folder. If you
are creating a new folder, you must also create the `_index.md`. For more
information, see the [`_index.md` template instructions](./template-_index-page.md).
[**Copy a version of this template without the instructions**](#copy-the-template)
@ -15,19 +20,43 @@ page. Example formatting template:
```yaml
---
# This section is called the "frontmatter" for your page
title: "Title for your page" # Use sentence case for titles
linkTitle: "Template: New docs page"
# The linkTitle field (above) is optional; use it to provide a shorter link if your page title is very long
weight: 50 # This affects the placement of the link in the sidebar on the left. Pages are ordered from top to bottom by weight, lowest to highest.
type: "docs" # You won't need to update this.
#aliases:
# - /docs/example/redirect/moved-renamed-page
# - /docs/another-example
# Has the page ever moved? If yes, include the prior location above, starting with path from the site root (for example /docs/, /blog/, or /community/). The old URL will redirect to this new file. For a new pages, "aliases" are not required.
title: ""
#linkTitle: ""
weight: 50
type: "docs"
---
```
```
<!--
# This section is called the "frontmatter" for your page that is defined in YAML.
title: ""
# The title of this page (renders at the top of the page). Use sentence case.
linkTitle: ""
# Optional: Use it to provide a shorter title for the page link so that it fits
# in the left navigation menu (to prevent wrapping)
weight: ""
# This specifies the vertical the placement of the page link in the left
# navigation menu. Pages are ordered from top (lowest weight) to bottom (highest weight).
type: "docs"
# You won't need to update this.
aliases:
- /docs/example/redirect/moved-renamed-page
- /docs/another-example
# Optional: Specifies a URL to redirect to this page.
# For example, has this page moved (are you replacing one or more deleted pages)?
# If yes, include the aliases frontmatter and specify the prior location of the
# page(s)/path(s) to redirect to this page. Specify the path and filename starting
# from the site root (for example /docs/, /blog/, or /community/).
-->
```
```
<!-- The page title you set in the frontmatter renders here (don't add a duplicate title) -->
```
Learn how to do something very cool.
```
@ -46,9 +75,11 @@ Generally, make sure you answer the questions:
## Before you begin
```
<!--
State all the requirements in this this section of the document.
Define any assumptions made (avoid tripping up the user and distracting them from the Knative feature you are trying to explain).
This is where you get past any of the non-Knative items so that you can focus on Knative-specific stuff below. For example:
State all the requirements in this section of the document.
Define any assumptions made (avoid tripping up the user and distracting them
from the Knative feature you are trying to explain).
This is where you get past any of the non-Knative items so that you can focus on
Knative-specific stuff below. For example:
-->
```
To complete the steps in this task, you must ..... meet/have/install/create/? the following:
@ -95,8 +126,9 @@ Introductory statement to define the goal of this sub-task and why its important
```
<!--
Put code into code blocks.
Markdown formatting: Use spaces, not tabs to indent code blocks, and leave one blank line before and after the block.
Examples:-->
Markdown formatting: Use spaces, not tabs to indent code blocks, and leave one
blank line before and after the block. Examples:
-->
<!--
1. Here's a code snippet:
@ -136,17 +168,39 @@ Now that you have an example running, learn how to enable .....:
# Copy the template
```yaml
---
# This section is called the "frontmatter" for your page
title: "Title for your page" # Use sentence case for titles
linkTitle: "Template: New docs page"
# The linkTitle field (above) is optional; use it to provide a shorter link if your page title is very long
weight: 50 # This affects the placement of the link in the sidebar on the left. Pages are ordered from top to bottom by weight, lowest to highest.
type: "docs" # You won't need to update this.
#aliases:
# - /docs/example/redirect/moved-renamed-page
# - /docs/another-example
# Has the page ever moved? If yes, include the prior location above, starting with path from the site root (for example /docs/, /blog/, or /community/). The old URL will redirect to this new file. For a new pages, "aliases" are not required.
title: ""
#linkTitle: ""
weight: 50
type: "docs"
---
<!--
# This section is called the "frontmatter" for your page that is defined in YAML.
title: ""
# The title of this page (renders at the top of the page). Use sentence case.
linkTitle: ""
# Optional: Use it to provide a shorter title for the page link so that it fits
# in the left navigation menu (to prevent wrapping)
weight: ""
# This specifies the vertical the placement of the page link in the left
# navigation menu. Pages are ordered from top (lowest weight) to bottom (highest weight).
type: "docs"
# You won't need to update this.
aliases:
- /docs/example/redirect/moved-renamed-page
- /docs/another-example
# Optional: Specifies a URL to redirect to this page.
# For example, has this page moved (are you replacing one or more deleted pages)?
# If yes, include the aliases frontmatter and specify the prior location of the
# page(s)/path(s) to redirect to this page. Specify the path and filename starting
# from the site root (for example /docs/, /blog/, or /community/).
-->
<!-- The page title you set in the frontmatter renders here (don't add a duplicate title) -->
Learn how to do something very cool.