mirror of https://github.com/knative/docs.git
New blog template and update doc template (#3341)
* New blog template/instructions * update and sync with new blog template * edits * add the copy section * fix formatting * update links for both templates * Add links to new content templates in PR template * typo * whitespace * more whitespace * and even more whitespace * trailing whitespace * whitespace * between
This commit is contained in:
RichieEscarez
GitHub
parent
c8b51931ed
commit
5d300af75e
|
|
@ -8,12 +8,17 @@ original PR. Best practice is to open a PR for the cherry-pick yourself after
|
|||
your original PR has been merged into the main branch. Once the cherry-pick PR
|
||||
has merged, remove the cherry-pick label from the original PR.
|
||||
|
||||
For more information on contributing to the Knative Docs, see:
|
||||
https://www.knative.dev/community/contributing/
|
||||
Use one of the new content templates:
|
||||
- [Documenation](./template-docs-page.md) -- Instructions and a template that
|
||||
you can use to help you add new documentation.
|
||||
- [Blog](./template-blog-entry.md) -- Instructions and a template that
|
||||
you can use to help you post to the Knative blog.
|
||||
|
||||
Learn more about contributing to the Knative Docs:
|
||||
https://github.com/knative/docs
|
||||
-->
|
||||
|
||||
Fixes #issue-number or description of the problem the PR solves
|
||||
"Fixes #issue-number" or "Add description of the problem this PR solves"
|
||||
|
||||
## Proposed Changes <!-- Describe the changes the PR makes. -->
|
||||
|
||||
|
|
|
|||
|
|
@ -57,9 +57,11 @@ We're excited that you're interested in contributing to the Knative documentatio
|
|||
- [How to contribute](./CONTRIBUTING.md) -- Contains information about how
|
||||
to contribute and outlines the roles for Docs contributors.
|
||||
|
||||
- [Template page](./new-page-template.md) -- A blank documentation page that
|
||||
demonstrates how to format a new page and includes tips on structuring your
|
||||
documentation.
|
||||
- New content templates:
|
||||
- [Documentation](./template-docs-page.md) -- Instructions and a template that
|
||||
you can use to help you add new documentation.
|
||||
- [Blog](./template-blog-entry.md) -- Instructions and a template that
|
||||
you can use to help you post to the Knative blog.
|
||||
|
||||
## Getting help
|
||||
|
||||
|
|
|
|||
|
|
@ -1,88 +0,0 @@
|
|||
# Documentation Template
|
||||
|
||||
This page is intended to provide best-practices for starting a new document.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
[Hugo](https://gohugo.io/) uses a set of metadata at the beginning of
|
||||
the page called
|
||||
[frontmatter](https://gohugo.io/content-management/front-matter/) to
|
||||
indicate information like the page title and link rendering in the
|
||||
sidebar.
|
||||
|
||||
Frontmatter needs to be formatted like this:
|
||||
```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.
|
||||
---
|
||||
```
|
||||
|
||||
This guide shows you how to do something very cool. Make sure to include
|
||||
a value proposition for the user: for example, this guide shows you how to do X,
|
||||
which is useful for doing Y and Z. Make sure you answer the questions "what does
|
||||
this guide show you how to do?" and "why would someone want to do this?".
|
||||
|
||||
## Before you begin
|
||||
|
||||
You need:
|
||||
|
||||
- A Kubernetes cluster with [Knative installed](docs/install/README.md). <!-- Update this relative link as needed,
|
||||
depending on where the new page is located in the file structure. -->
|
||||
- Anything else?
|
||||
|
||||
## Break steps into logical sections
|
||||
|
||||
Avoid nesting headings directly on top of each other with no text in between.
|
||||
|
||||
1. Use ordered lists for steps.
|
||||
|
||||
1. Step number two.
|
||||
|
||||
1. Step number three.
|
||||
|
||||
<!-- GitHub's markdown processor will correctly automate the numbers in ordered
|
||||
lists if every list item starts with one. Our site has a known issue with
|
||||
rendering the numbers in ordered lists (see https://github.com/knative/docs/issues/1202)
|
||||
but we still recommend contributors avoid manually numbered ordered lists. -->
|
||||
|
||||
### You can use smaller sections within sections for related tasks
|
||||
|
||||
Avoid nesting headings directly on top of each other with no text in between.
|
||||
|
||||
Put code into a code block.
|
||||
|
||||
1. Here's a code snippet:
|
||||
<!-- Use spaces and not tabs to indent code blocks, and leave one blank line before and after the block. -->
|
||||
```bash
|
||||
kubectl apply --filename test.yaml
|
||||
```
|
||||
1. Another code snippet:
|
||||
|
||||
```bash
|
||||
kubectl apply --filename test2.yaml
|
||||
```
|
||||
|
||||
Always explain code snippets thoroughly so that how they work or what they do
|
||||
is clear.
|
||||
|
||||
## Cleaning up
|
||||
|
||||
If your guide installs a sample application, show the user how to delete it.
|
||||
|
||||
## What's next
|
||||
|
||||
Provide links to other relevant topics, if applicable. Once someone has
|
||||
completed these steps, what might they want to do next?
|
||||
|
||||
- [Link](./search.md) <!-- Always use relative links if linking to a page within the Docs repo. -->
|
||||
- [Link](./search.md)
|
||||
- [Link](./search.md)
|
||||
|
|
@ -0,0 +1,163 @@
|
|||
# Blog template instructions
|
||||
|
||||
An example template 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)
|
||||
|
||||
## 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
|
||||
---
|
||||
# This section is called the "frontmatter" for your page
|
||||
title: "Title for your page" # Use sentence case for titles and headings
|
||||
linkTitle: "A shorten title" # Optional: Use/render a shorter title in the navigation menu.
|
||||
author: "" # Your name
|
||||
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
|
||||
---
|
||||
```
|
||||
|
||||
Include a commented-out table with tracking info about reviews and approvals:
|
||||
```
|
||||
<!--
|
||||
| Reviewer | Date | Approval |
|
||||
| ------------------ | ---------- | ------------- |
|
||||
| <!-- GitHub ID --> | YYYY-MM-DD | :+1:, :monocle_face:, :-1: |
|
||||
| <!-- GitHub ID --> | YYYY-MM-DD | :+1:, :monocle_face:, :-1: |
|
||||
-->
|
||||
```
|
||||
|
||||
## Blog content body
|
||||
```
|
||||
<!--
|
||||
Introduce the feature you are going to explain:
|
||||
* state what the goal of this blog entry is
|
||||
* how you use the feature
|
||||
* make sure to link to the corresponding docs
|
||||
* why others can find it useful (why its important)
|
||||
-->
|
||||
```
|
||||
|
||||
```
|
||||
<!-- Add/create as many distinct Steps or Sections as needed. -->
|
||||
```
|
||||
### Example step/section 1:
|
||||
```
|
||||
<!--
|
||||
An introductory sentence about this step or section (ie. why its important and what the result is).
|
||||
Don't forget to link to any new or related concepts that you mention here.
|
||||
-->
|
||||
```
|
||||
|
||||
### Example step/section 2:
|
||||
```
|
||||
<!--
|
||||
An introductory sentence about this step or section (ie. why its important, how it relates to the one before, and what the result is)
|
||||
Don't forget to link to any new or related concepts that you mention here.
|
||||
-->
|
||||
```
|
||||
|
||||
### Example step/section 3:
|
||||
```
|
||||
<!--
|
||||
An introductory sentence about this step or section (ie. why its important, how it relates to the one before, and what the result is)
|
||||
Don't forget to link to any new or related concepts that you mention here.
|
||||
-->
|
||||
```
|
||||
|
||||
### Example section about results
|
||||
```
|
||||
<!--
|
||||
Tie it all together and briefly revisit the main key points and then the overall result/goal/importance
|
||||
-->
|
||||
```
|
||||
|
||||
## Further reading
|
||||
```
|
||||
<!--
|
||||
Add any links to other related resources that users might find useful.
|
||||
What's the next step?
|
||||
-->
|
||||
```
|
||||
|
||||
## About the author
|
||||
```
|
||||
<!--
|
||||
Add a short bio of yourself here
|
||||
-->
|
||||
```
|
||||
|
||||
# Copy the template
|
||||
|
||||
```
|
||||
---
|
||||
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
|
||||
---
|
||||
|
||||
<!--
|
||||
| Reviewer | Date | Approval |
|
||||
| ------------------ | ---------- | ------------- |
|
||||
| <!-- GitHub ID --> | YYYY-MM-DD | :+1:, :monocle_face:, :-1: |
|
||||
| <!-- GitHub ID --> | YYYY-MM-DD | :+1:, :monocle_face:, :-1: |
|
||||
-->
|
||||
|
||||
## Blog content body
|
||||
<!-- Introduce the feature you are going to explain:
|
||||
* state what the goal of this blog entry is
|
||||
* how you use the feature
|
||||
* make sure to link to the corresponding docs
|
||||
* why others can find it useful (why its important)
|
||||
-->
|
||||
|
||||
<!-- Add/create as many distinct Steps or Sections as needed. -->
|
||||
### Example step/section 1:
|
||||
<!--
|
||||
An introductory sentence about this step or section (ie. why its important and what the result is).
|
||||
Don't forget to link to any new or related concepts that you mention here.
|
||||
-->
|
||||
|
||||
### Example step/section 2:
|
||||
<!--
|
||||
An introductory sentence about this step or section (ie. why its important, how it relates to the one before, and what the result is)
|
||||
Don't forget to link to any new or related concepts that you mention here.
|
||||
-->
|
||||
|
||||
### Example step/section 3:
|
||||
<!--
|
||||
An introductory sentence about this step or section (ie. why its important, how it relates to the one before, and what the result is)
|
||||
Don't forget to link to any new or related concepts that you mention here.
|
||||
-->
|
||||
|
||||
### Example section about results
|
||||
<!--
|
||||
Tie it all together and briefly revisit the main key points and then the overall result/goal/importance
|
||||
-->
|
||||
|
||||
## Further reading
|
||||
<!--
|
||||
Add any links to related resources that users might find useful.
|
||||
What's the next step?
|
||||
-->
|
||||
|
||||
## About the author
|
||||
<!--
|
||||
Add a short bio of yourself here
|
||||
-->
|
||||
```
|
||||
|
|
@ -0,0 +1,243 @@
|
|||
# Documentation template instructions
|
||||
|
||||
An example template that you can use to provide best-practices for starting a new how-to document.
|
||||
|
||||
[**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
|
||||
---
|
||||
# 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.
|
||||
---
|
||||
```
|
||||
|
||||
Learn how to do something very cool.
|
||||
|
||||
```
|
||||
<!--
|
||||
Make sure to state the goal of this **task-oriented
|
||||
content** 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 guide show you how to do?"
|
||||
- "why would someone want to do this?"
|
||||
-->
|
||||
```
|
||||
|
||||
## 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:
|
||||
-->
|
||||
```
|
||||
To complete the steps in this task, you must ..... meet/have/install/create/? the following:
|
||||
|
||||
- A Kubernetes cluster with [Knative installed](./docs/install/README.md).
|
||||
<!-- Make sue to use relative links. -->
|
||||
- The latest version of ... running?
|
||||
- Privileges to .....
|
||||
- Any other requirement?
|
||||
|
||||
## Break steps into logical sections
|
||||
```
|
||||
<!--
|
||||
Avoid nesting headings directly on top of each other without text/explanation/context between.
|
||||
-->
|
||||
```
|
||||
|
||||
Introductory statement to define the goal of these steps and the role they play in this document (why its important?):
|
||||
|
||||
1. Use ordered lists for steps.
|
||||
|
||||
* Use bulleted lists for options:
|
||||
|
||||
1. Sub step one
|
||||
1. Sub step two
|
||||
|
||||
* Option two:
|
||||
|
||||
Explain the value of why a user would choose this option.
|
||||
|
||||
1. Step number two.
|
||||
|
||||
1. Step number three.
|
||||
|
||||
### Use a sub-section to group related sub-tasks
|
||||
```
|
||||
<!--
|
||||
Avoid nesting headings directly on top of each other without text/explanation/context between.
|
||||
-->
|
||||
```
|
||||
|
||||
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:-->
|
||||
<!--
|
||||
1. Here's a code snippet:
|
||||
|
||||
```bash
|
||||
kubectl apply --filename test.yaml
|
||||
```-->
|
||||
<!--
|
||||
1. Another inline code snippet with the `kubectl apply` command.
|
||||
-->
|
||||
```
|
||||
|
||||
## Cleaning up
|
||||
```
|
||||
<!--
|
||||
If this "how-to" guide installs a sample application, creates and runs resources that might cost unnecessary fees, you should show the user how to delete or remove.
|
||||
-->
|
||||
```
|
||||
|
||||
Run the following command to stop/remove/avoid running this example and prevent incurring fees from your cloud provider/your cluster/etc.
|
||||
|
||||
## What's next
|
||||
```
|
||||
<!--
|
||||
Link to relevant topics, if applicable. Once someone has
|
||||
completed these steps, what might they want to do next?
|
||||
Remember to keep it focused and targeted, too many links are not as useful.
|
||||
-->
|
||||
```
|
||||
|
||||
Now that you have an example running, learn how to enable .....:
|
||||
|
||||
- [Link](./serving/example.md) <!-- Always use relative links if linking to a page within the Docs repo. -->
|
||||
- [Link](./eventing/example.md)
|
||||
- [Link](./search-example.md)
|
||||
|
||||
|
||||
# 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.
|
||||
---
|
||||
|
||||
Learn how to do something very cool.
|
||||
|
||||
<!--
|
||||
Make sure to state the goal of this **task-oriented
|
||||
content** 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 guide show you how to do?"
|
||||
- "why would someone want to do this?"
|
||||
-->
|
||||
|
||||
|
||||
## 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:
|
||||
-->
|
||||
|
||||
To complete the steps in this task, you must ..... meet/have/install/create/? the following:
|
||||
|
||||
- A Kubernetes cluster with [Knative installed](./docs/install/README.md).
|
||||
<!-- Make sue to use relative links. -->
|
||||
- The latest version of ... running?
|
||||
- Privileges to .....
|
||||
- Any other requirement?
|
||||
|
||||
## Break steps into logical sections
|
||||
<!--
|
||||
Avoid nesting headings directly on top of each other without text/explanation/context between.
|
||||
-->
|
||||
|
||||
Introductory statement to define the goal of these steps and the role they play in this document (why its important?):
|
||||
|
||||
1. Use ordered lists for steps.
|
||||
|
||||
* Use bulleted lists for options:
|
||||
|
||||
1. Sub step one
|
||||
1. Sub step two
|
||||
|
||||
* Option two:
|
||||
|
||||
Explain the value of why a user would choose this option.
|
||||
|
||||
1. Step number two.
|
||||
|
||||
1. Step number three.
|
||||
|
||||
### Use a sub-section to group related sub-tasks
|
||||
<!--
|
||||
Avoid nesting headings directly on top of each other without text/explanation/context between.
|
||||
-->
|
||||
|
||||
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:-->
|
||||
<!--
|
||||
1. Here's a code snippet:
|
||||
|
||||
```bash
|
||||
kubectl apply --filename test.yaml
|
||||
```-->
|
||||
<!--
|
||||
1. Another inline code snippet with the `kubectl apply` command.
|
||||
-->
|
||||
|
||||
## Cleaning up
|
||||
<!--
|
||||
If this "how-to" guide installs a sample application, creates and runs resources that might cost unnecessary fees, you should show the user how to delete or remove.
|
||||
-->
|
||||
|
||||
Run the following command to stop/remove/avoid running this example and prevent incurring fees from your cloud provider/your cluster/etc.
|
||||
|
||||
## What's next
|
||||
<!--
|
||||
Link to relevant topics, if applicable. Once someone has
|
||||
completed these steps, what might they want to do next?
|
||||
Remember to keep it focused and targeted, too many links are not as useful.
|
||||
-->
|
||||
|
||||
Now that you have an example running, learn how to enable .....:
|
||||
|
||||
- [Link](./serving/example.md) <!-- Always use relative links if linking to a page within the Docs repo. -->
|
||||
- [Link](./eventing/example.md)
|
||||
- [Link](./search-example.md)
|
||||
|
||||
```
|
||||
Loading…
Reference in New Issue