mirror of https://github.com/istio/istio.io.git
17 KiB
17 KiB
| title | description | weight | aliases | keywords | ||
|---|---|---|---|---|---|---|
| Writing a New Topic | Explains the mechanics of creating new documentation pages. | 30 |
|
|
This page shows how to create a new Istio documentation topic.
Before you begin
You first need to create a fork of the Istio documentation repository as described in Working with GitHub.
Choosing a page type
As you prepare to write a new topic, think about which of these page types is the best fit for your content:
| Concept | A concept page explains some significant aspect of Istio. For example, a concept page might describe the Mixer's configuration model and explain some of its subtleties. Typically, concept pages don't include sequences of steps, but instead provide links to tasks that do. |
| Reference | A reference page provides exhaustive lists of things like API parameters, command-line options, configuration settings, and procedures. |
| Examples | An example page describes a fully working stand-alone example highlighting a particular set of features. Examples must have easy to follow setup and usage instructions so users can quickly run the sample themselves and experiment with changing the example to explore the system. |
| Task | A task page shows how to do a single thing, typically by giving a short sequence of steps. Task pages have minimal explanation, but often provide links to conceptual topics that provide related background and knowledge. |
| Setup | A setup page is similar to a task page, except that it is focused on installation activities. |
| Blog Post | A blog post is a timely article on Istio or products and technologies related to it. |
Naming a topic
Choose a title for your topic that has the keywords you want search engines to find. Create a filename for your topic that uses the words in your title, separated by hyphens, all in lower case.
Updating the front matter
Every documentation file needs to start with front matter. The front matter is a block of YAML that is between the triple-dashed lines at the top of each file. Here's the chunk of front matter you should start with: