From 5d300af75e092416e99b77eea2038fec007b0e85 Mon Sep 17 00:00:00 2001 From: RichieEscarez Date: Fri, 12 Mar 2021 05:59:28 -0800 Subject: [PATCH] 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 --- .github/pull-request-template.md | 11 +- README.md | 8 +- new-page-template.md | 88 ----------- template-blog-entry.md | 163 +++++++++++++++++++++ template-docs-page.md | 243 +++++++++++++++++++++++++++++++ 5 files changed, 419 insertions(+), 94 deletions(-) delete mode 100644 new-page-template.md create mode 100644 template-blog-entry.md create mode 100644 template-docs-page.md diff --git a/.github/pull-request-template.md b/.github/pull-request-template.md index 9792ac450..2599233e9 100644 --- a/.github/pull-request-template.md +++ b/.github/pull-request-template.md @@ -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 diff --git a/README.md b/README.md index a19c7cfee..c1682ea18 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/new-page-template.md b/new-page-template.md deleted file mode 100644 index 8e97252df..000000000 --- a/new-page-template.md +++ /dev/null @@ -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). -- 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. - - - -### 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: - - ```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) -- [Link](./search.md) -- [Link](./search.md) diff --git a/template-blog-entry.md b/template-blog-entry.md new file mode 100644 index 000000000..c08a6fb03 --- /dev/null +++ b/template-blog-entry.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/" # 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: +``` + | YYYY-MM-DD | :+1:, :monocle_face:, :-1: | +| | YYYY-MM-DD | :+1:, :monocle_face:, :-1: | +--> +``` + +## Blog content body +``` + +``` + +``` + +``` +### Example step/section 1: +``` + +``` + +### Example step/section 2: +``` + +``` + +### Example step/section 3: +``` + +``` + +### Example section about results +``` + +``` + +## Further reading +``` + +``` + +## About the author +``` + +``` + +# Copy the template + +``` +--- +title: "" +linkTitle: "" +author: "" +authorHandle: "" +date: "" # Publishing date +description: "" # A short one-liner describing this blog entry +folderWithMediaFiles: "./images/" # The relative file path (ie. new folder) to any images, etc. +keywords: Releases, Steering committee, Demo, Events # Meta keywords for the content +--- + + | YYYY-MM-DD | :+1:, :monocle_face:, :-1: | +| | YYYY-MM-DD | :+1:, :monocle_face:, :-1: | +--> + +## Blog content body + + + +### Example step/section 1: + + +### Example step/section 2: + + +### Example step/section 3: + + +### Example section about results + + +## Further reading + + +## About the author + +``` diff --git a/template-docs-page.md b/template-docs-page.md new file mode 100644 index 000000000..a3610532f --- /dev/null +++ b/template-docs-page.md @@ -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. + +``` + +``` + +## Before you begin +``` + +``` +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). + +- The latest version of ... running? +- Privileges to ..... +- Any other requirement? + +## Break steps into logical sections +``` + +``` + +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 +``` + +``` + +Introductory statement to define the goal of this sub-task and why its important: + +``` + + + +``` + +## Cleaning up +``` + +``` + +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 +``` + +``` + +Now that you have an example running, learn how to enable .....: + +- [Link](./serving/example.md) +- [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. + + + + +## Before you begin + + +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). + +- The latest version of ... running? +- Privileges to ..... +- Any other requirement? + +## Break steps into logical sections + + +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 + + +Introductory statement to define the goal of this sub-task and why its important: + + + + + +## Cleaning up + + +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 + + +Now that you have an example running, learn how to enable .....: + +- [Link](./serving/example.md) +- [Link](./eventing/example.md) +- [Link](./search-example.md) + +```