mirror of https://github.com/knative/docs.git
Salvage old contributor docs (#4020)
* Culled old contributor docs * Fixed links * Fix links to templates * Revert "Fix links to templates" This reverts commit2025fed68e. * Fixes for template links * Revert "Fixes for template links" This reverts commit691cdcc965. * Some fixes for the template links * Revert "Some fixes for the template links" This reverts commita1762749c4. * Removed broken links * Fixed link to style guide readme * Remove faulty link to style guide * Update docs/help/contributor/creating-new-docs.md Co-authored-by: Ashleigh Brennan <abrennan@redhat.com> * Update docs/help/contributor/creating-new-docs.md Co-authored-by: Ashleigh Brennan <abrennan@redhat.com> * Changed Docs WG references and some punctuation * Added links * Revert "Added links" This reverts commitcb5ddb759b. * Moved templates and changed links * Fixing links Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>
This commit is contained in:
RichardJJG
GitHub
parent
7aba7060a8
commit
21fe8c783a
|
|
@ -9,14 +9,14 @@ 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.
|
||||
|
||||
Use one of the new content templates:
|
||||
- [Concept](./template-concept.md) -- Conceptual topics explain how things work or what things mean.
|
||||
They provide helpful context to readers. They do not include procedures.
|
||||
- [Procedure](./template-procedure.md) -- Procedural (how-to) topics include detailed steps to
|
||||
perform a task as well as some context about the task.
|
||||
- [Troubleshooting](./template-troubleshooting.md) -- Troubleshooting topics list common errors and
|
||||
solutions.
|
||||
- [Blog](./template-blog-entry.md) -- Instructions and a template that you can use to help you post
|
||||
to the Knative blog.
|
||||
- [Concept](./docs/contributor/templates/template-concept.md) -- Conceptual topics explain how things
|
||||
work or what things mean. They provide helpful context to readers. They do not include procedures.
|
||||
- [Procedure](./docs/contributor/templates/template-procedure.md) -- Procedural (how-to) topics
|
||||
include detailed steps to perform a task as well as some context about the task.
|
||||
- [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md) -- Troubleshooting
|
||||
topics list common errors and solutions.
|
||||
- [Blog](./docs/contributor/templates/template-blog-entry.md) -- Instructions and a template that you
|
||||
can use to help you post to the Knative blog.
|
||||
|
||||
Consult [Knative contributor's guide](./help/contributing) for all resources for contributing to
|
||||
Knative documentation.
|
||||
|
|
|
|||
|
|
@ -5,11 +5,11 @@ into a single location:
|
|||
#### [Go to the How-to guides for Knative docs contributors](https://knative.dev/help/)
|
||||
|
||||
**Quick links**:
|
||||
* [Docs help](https://knative.dev/help/contributor/)
|
||||
* New content templates:
|
||||
* [Concept](template-concept.md)
|
||||
* [Procedure](template-procedure.md)
|
||||
* [Troubleshooting](template-troubleshooting.md)
|
||||
* [Blog](template-blog-entry.md)
|
||||
* [Website help](https://knative.dev/help/contributor/publishing)
|
||||
* [Maintainer help](https://knative.dev/help/maintainer/)
|
||||
* [Docs help](https://knative.dev/help/contributor/)
|
||||
* New content templates:
|
||||
* [Concept](./docs/contributor/templates/template-concept.md)
|
||||
* [Procedure](./docs/contributor/templates/template-procedure.md)
|
||||
* [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md)
|
||||
* [Blog](./docs/contributor/templates/template-blog-entry.md)
|
||||
* [Website help](https://knative.dev/help/contributor/publishing)
|
||||
* [Maintainer help](https://knative.dev/help/maintainer/)
|
||||
|
|
|
|||
|
|
@ -14,9 +14,9 @@ into a single location:
|
|||
**Quick links**:
|
||||
* [Docs help](https://knative.dev/help/contributor/)
|
||||
* New content templates:
|
||||
* [Concept](template-concept.md)
|
||||
* [Procedure](template-procedure.md)
|
||||
* [Troubleshooting](template-troubleshooting.md)
|
||||
* [Blog](template-blog-entry.md)
|
||||
* [Concept](./docs/contributor/templates/template-concept.md)
|
||||
* [Procedure](./docs/contributor/templates/template-procedure.md)
|
||||
* [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md)
|
||||
* [Blog](./docs/contributor/templates/template-blog-entry.md)
|
||||
* [Website help](https://knative.dev/help/contributor/publishing)
|
||||
* [Maintainer help](https://knative.dev/help/maintainer/)
|
||||
|
|
|
|||
|
|
@ -66,10 +66,10 @@ We're excited that you're interested in contributing to the Knative documentatio
|
|||
to contribute.
|
||||
|
||||
- New content templates:
|
||||
- [Concept](template-concept.md)
|
||||
- [Procedure](template-procedure.md)
|
||||
- [Troubleshooting](template-troubleshooting.md)
|
||||
- [Blog](template-blog-entry.md)
|
||||
- [Concept](./docs/contributor/templates/template-concept.md)
|
||||
- [Procedure](./docs/contributor/templates/template-procedure.md)
|
||||
- [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md)
|
||||
- [Blog](./docs/contributor/templates/template-blog-entry.md)
|
||||
|
||||
## Getting help
|
||||
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@ into a single location:
|
|||
**Quick links**:
|
||||
* [Docs help](https://knative.dev/help/contributor/)
|
||||
* New content templates:
|
||||
* [Concept](template-concept.md)
|
||||
* [Procedure](template-procedure.md)
|
||||
* [Troubleshooting](template-troubleshooting.md)
|
||||
* [Blog](template-blog-entry.md)
|
||||
* [Concept](./docs/contributor/templates/template-concept.md)
|
||||
* [Procedure](./docs/contributor/templates/template-procedure.md)
|
||||
* [Troubleshooting](./docs/contributor/templates/template-troubleshooting.md)
|
||||
* [Blog](./docs/contributor/templates/template-blog-entry.md)
|
||||
* [Website help](https://knative.dev/help/contributor/publishing)
|
||||
* [Maintainer help](https://knative.dev/help/maintainer/)
|
||||
|
|
|
|||
|
|
@ -1,11 +1,4 @@
|
|||
---
|
||||
title: "Joining the project and getting started"
|
||||
linkTitle: "Join"
|
||||
weight: 10
|
||||
type: "docs"
|
||||
---
|
||||
|
||||
|
||||
# Becoming a contributor
|
||||
|
||||
## Join to become a contributor
|
||||
|
||||
|
|
@ -57,9 +50,6 @@ Knative documentation:
|
|||
|
||||
- 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)
|
||||
|
|
@ -108,10 +98,3 @@ 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)
|
||||
|
|
@ -1,9 +1,4 @@
|
|||
---
|
||||
title: "Code samples"
|
||||
linkTitle: ""
|
||||
weight: 100
|
||||
type: "docs"
|
||||
---
|
||||
# Code samples
|
||||
|
||||
There are currently two general types of content that focus on code samples,
|
||||
either internal contributor content, or external-facing user content.
|
||||
|
|
@ -1,12 +1,6 @@
|
|||
---
|
||||
title: "Creating blog posts"
|
||||
linkTitle: "New blog post"
|
||||
weight: 30
|
||||
type: "docs"
|
||||
showlandingtoc: "false"
|
||||
---
|
||||
# Creating blog posts
|
||||
|
||||
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).
|
||||
The Knative blog is owned by the [DUX working group](https://knative.dev/community/contributing/working-groups/working-groups/#documentation--user-experience).
|
||||
|
||||
This section covers documentation, processes, and roles for the [Knative blog](https://knative.dev/blog/).
|
||||
|
||||
|
|
@ -41,7 +35,7 @@ To submit a blog post, follow the steps below.
|
|||
#### 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)
|
||||
- Tutorials and demos
|
||||
- Use cases
|
||||
- Content that is specific to a vendor or platform about Knative installation and use
|
||||
|
||||
|
|
@ -1,26 +1,25 @@
|
|||
---
|
||||
title: "Adding new documentation"
|
||||
linkTitle: "New docs"
|
||||
weight: 20
|
||||
type: "docs"
|
||||
showlandingtoc: "false"
|
||||
---
|
||||
# Creating new documentation
|
||||
|
||||
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. Use one of the new content templates:
|
||||
- [Concept](templates/template-concept.md) -- Conceptual topics explain how
|
||||
things work or what things mean. They provide helpful context to readers. They do not include
|
||||
procedures.
|
||||
- [Procedure](templates/template-procedure.md) -- Procedural (how-to) topics
|
||||
include detailed steps to perform a task as well as some context about the task.
|
||||
- [Troubleshooting](templates/template-troubleshooting.md) -- Troubleshooting
|
||||
topics list common errors and solutions.
|
||||
- [Blog](templates/template-blog-entry.md) -- Instructions and a template
|
||||
that you can use to help you post to the Knative blog.
|
||||
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. Write your new content. See the [style guide](style-guide/README.md) to help you with this
|
||||
process. Feel free to reach out to the
|
||||
[DUX working group](https://knative.dev/community/contributing/working-groups/working-groups/#documentation--user-experience) 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).
|
||||
to kick off the review process. For details, see our [Using GitHub help](/github.md#prs).
|
||||
|
||||
## Identify the audience and intended use
|
||||
|
||||
|
|
@ -30,9 +29,9 @@ 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 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
|
||||
|
|
@ -58,8 +57,8 @@ 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.
|
||||
and answer all your questions during the [DUX working group](https://knative.dev/community/contributing/working-groups/working-groups/#documentation--user-experience)
|
||||
weekly meetings.
|
||||
|
||||
## Content types
|
||||
|
||||
|
|
@ -77,7 +76,7 @@ their intended audiences, and the goals each type strives to achieve:
|
|||
</tr>
|
||||
</thead>
|
||||
<tr>
|
||||
<td>Concepts</td>
|
||||
<td>Concept</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
|
||||
|
|
@ -86,7 +85,7 @@ their intended audiences, and the goals each type strives to achieve:
|
|||
knowledge of the project.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Reference pages</td>
|
||||
<td>Reference</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
|
||||
|
|
@ -96,7 +95,7 @@ their intended audiences, and the goals each type strives to achieve:
|
|||
needs specific bits of information to complete advanced tasks.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Examples</td>
|
||||
<td>Example</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
|
||||
|
|
@ -107,23 +106,23 @@ their intended audiences, and the goals each type strives to achieve:
|
|||
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
|
||||
<td>Procedure</td>
|
||||
<td>Shows how to achieve a single goal using Knative features. Procedures are written
|
||||
as a sequence of steps. Procedures provide minimal
|
||||
explanation of the features, but include links to the concepts that
|
||||
provide the related background and knowledge. Tasks must include automated
|
||||
provide the related background and knowledge. Procedures 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>Setup</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>Blog</td>
|
||||
<td>
|
||||
Focus on Knative or products and technologies related to it. Blog posts fall in one of the following three categories:
|
||||
<ul>
|
||||
|
|
@ -136,7 +135,7 @@ their intended audiences, and the goals each type strives to achieve:
|
|||
about it in an anecdotal, experiential, and more informal way.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>News entries</td>
|
||||
<td>News</td>
|
||||
<td>
|
||||
Focus on timely information about Knative and related events. News entries typically announce new releases or upcoming events.
|
||||
</td>
|
||||
|
|
@ -144,7 +143,7 @@ their intended audiences, and the goals each type strives to achieve:
|
|||
the Knative community.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FAQ entries</td>
|
||||
<td>FAQ</td>
|
||||
<td>
|
||||
Provide quick answers to common questions. Answers don't introduce any
|
||||
concepts. Instead, they provide practical advice or insights. Answers
|
||||
|
|
@ -154,7 +153,7 @@ their intended audiences, and the goals each type strives to achieve:
|
|||
resources to learn more.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Operation guides</td>
|
||||
<td>Operation guide</td>
|
||||
<td>
|
||||
Focus on practical solutions that address specific problems encountered while running Knative in a real-world setting.
|
||||
</td>
|
||||
|
|
@ -171,7 +170,7 @@ search engines to find and use sentence style capitalization.
|
|||
|
||||
#### New files
|
||||
|
||||
The filename of your new content should reflect that the title.
|
||||
The filename of your new content should reflect the title.
|
||||
|
||||
#### New files and folders
|
||||
|
||||
|
|
@ -183,12 +182,7 @@ 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)
|
||||
If you are not familiar with GitHub, see our [working with GitHub guide](/github.md)
|
||||
to learn how to submit documentation changes.
|
||||
|
|
@ -1,21 +1,9 @@
|
|||
---
|
||||
title: "GitHub workflow for Knative documentation"
|
||||
linkTitle: "Using GitHub"
|
||||
weight: 10
|
||||
type: "docs"
|
||||
---
|
||||
# GitHub workflow for Knative documentation
|
||||
|
||||
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}
|
||||
## Set up your local machine
|
||||
|
||||
To check out your fork of the `knative/docs` repository:
|
||||
|
||||
|
|
@ -42,7 +30,7 @@ You are now able to open PRs, start reviews, and contribute fixes the
|
|||
[syncing your fork](https://help.github.com/articles/syncing-a-fork/).
|
||||
|
||||
|
||||
## Reporting documentation issues{#issues}
|
||||
## Report documentation issues
|
||||
|
||||
<!-- This could use a pass to reduce the overhead for filing new issues,
|
||||
and to consolidate items more easily during issue triage. -->
|
||||
|
|
@ -77,7 +65,7 @@ the issue in the
|
|||
[`knative/website` repo](https://github.com/knative/website/issues).
|
||||
|
||||
|
||||
## Fixing documentation issues (Opening PRs){#prs}
|
||||
## Open PRs to fix documentation issues
|
||||
|
||||
The Knative documentation follows the standard
|
||||
[GitHub collaboration flow](https://guides.github.com/introduction/flow/)
|
||||
|
|
@ -171,7 +159,7 @@ If you want to notify and include other stakeholders in your PR review, use the
|
|||
[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}
|
||||
## Using Prow to manage PRs and Issues
|
||||
|
||||
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
|
||||
|
|
@ -202,3 +190,18 @@ the known commands:
|
|||
|
||||
- See the [Branches](./structure/#branches) section for details about how
|
||||
to use the `/cherrypick` command.
|
||||
|
||||
### Common GitHub PRs FAQs
|
||||
|
||||
* 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.
|
||||
|
||||
* 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 re-running 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.
|
||||
|
||||
* Other Issues/Unsure -- reach out in the #docs Slack channel and someone will be happy to help out.
|
||||
|
|
@ -1,9 +1,4 @@
|
|||
---
|
||||
title: "Content structure"
|
||||
linkTitle: ""
|
||||
weight: 20
|
||||
type: "docs"
|
||||
---
|
||||
# Content structure
|
||||
|
||||
**TODO: link to intended documentation layout.** A general warning about
|
||||
[Conway's Law](https://en.wikipedia.org/wiki/Conway%27s_law): documents will
|
||||
|
|
@ -17,7 +12,7 @@ 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)
|
||||
[Learn about documenting code samples](/code-samples.md)
|
||||
|
||||
|
||||
## Branches
|
||||
|
|
@ -211,7 +211,7 @@ If the note regards an issue that could lead to data loss, the note should be a
|
|||
|
||||
The following is an embedded image reference in markdown.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### Tabs
|
||||
|
|
@ -1,20 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
---
|
||||
title: "How-to for documentation"
|
||||
linkTitle: "How-tos"
|
||||
weight: "40"
|
||||
type: "docs"
|
||||
showlandingtoc: "true"
|
||||
---
|
||||
|
|
@ -1,113 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -1,118 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
||||
|
|
@ -1,56 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
||||
STATUS: 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 variables 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
|
||||
|
|
@ -1,116 +0,0 @@
|
|||
---
|
||||
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)
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
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" %}}
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
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" %}}
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
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" %}}
|
||||
|
|
@ -1,187 +0,0 @@
|
|||
---
|
||||
title: "Staging and publishing Knative documentation"
|
||||
linkTitle: "Preview Website"
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/knative/docs.git
|
||||
```
|
||||
|
||||
You may also want to clone the community repo:
|
||||
|
||||
```bash
|
||||
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/):
|
||||
|
||||
```bash
|
||||
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):
|
||||
|
||||
```bash
|
||||
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
26
help/faqs.md
|
|
@ -1,26 +0,0 @@
|
|||
---
|
||||
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.
|
||||
Loading…
Reference in New Issue