PLEASE NOTE: This document applies to the HEAD of the source tree
If you are using a released version of Kubernetes, you should
refer to the docs that go with that version.
The latest 1.0.x release of this document can be found
[here](http://releases.k8s.io/release-1.0/docs/devel/how-to-doc.md).
Documentation for other releases can be found at
[releases.k8s.io](http://releases.k8s.io).
--
Document Conventions
====================
Updated: 11/3/2015
*This document is oriented at users and developers who want to write documents for Kubernetes.*
**Table of Contents**
- [What Are Mungers?](#what-are-mungers)
- [Table of Contents](#table-of-contents)
- [Writing Examples](#writing-examples)
- [Adding Links](#adding-links)
- [Auto-added Mungers](#auto-added-mungers)
- [Unversioned Warning](#unversioned-warning)
- [Is Versioned](#is-versioned)
- [Generate Analytics](#generate-analytics)
## What Are Mungers?
Mungers are like gofmt for md docs which we use to format documents. To use it, simply place
```
```
in your md files. Note that xxxx is the placeholder for a specific munger. Appropriate content will be generated and inserted between two brackets after you run `hack/update-generated-docs.sh`. See [munger document](../../cmd/mungedocs/) for more details.
## Table of Contents
Instead of writing table of contents by hand, use the TOC munger:
```
```
## Writing Examples
Sometimes you may want to show the content of certain example files. Use EXAMPLE munger whenever possible:
```
```
This way, you save the time to do the copy-and-paste; what's better, the content won't become out-of-date everytime you update the example file.
For example, the following munger:
```
```
generates
```yaml
apiVersion: v1
kind: Pod
metadata:
name: nginx
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx
ports:
- containerPort: 80
```
[Download example](../user-guide/pod.yaml?raw=true)
## Adding Links
Use inline link instead of url at all times. When you add internal links from `docs/` to `docs/` or `examples/`, use relative links; otherwise, use `http://releases.k8s.io/HEAD/`. For example, use:
```
[GCE](../getting-started-guides/gce.md) # note that it's under docs/
[Kubernetes package](http://releases.k8s.io/HEAD/pkg/) # note that it's under pkg/
[Kubernetes](http://kubernetes.io/)
```
and avoid using:
```
[GCE](https://github.com/kubernetes/kubernetes/blob/master/docs/getting-started-guides/gce.md)
[Kubernetes package](../../pkg/)
http://kubernetes.io/
```
## Auto-added Mungers
Some mungers are auto-added. You don't have to add them manually, and `hack/update-generated-docs.sh` does that for you. It's recommended to just read this section as a reference instead of messing up with the following mungers.
### Unversioned Warning
UNVERSIONED_WARNING munger inserts unversioned warning which warns the users when they're reading the document from HEAD and informs them where to find the corresponding document for a specific release.
```
```
### Is Versioned
IS_VERSIONED munger inserts `IS_VERSIONED` tag in documents in each release, which stops UNVERSIONED_WARNING munger from inserting warning messages.
```
```
### Generate Analytics
ANALYTICS munger inserts a Google Anaylytics link for this page.
```
```
[]()