message: docs: add documentation guide
diff: @@ -10,14 +10,88 @@ options:
  * **Audience**: Eyerone
  * **Level**: Beginner
  -### Outline
  +### What to expect
  -* Learn about documentation support in patternplate
  * Add local documentation to a pattern
  +* Learn about global docs in patternplate
  ### You'll need
  * Text editor
  * **patternplate project**
  + * Follow along our [Getting Started Guide](./doc/docs/guides/getting-started) to bootstrap one.
  + * A completed copy is available via `git clone https://github.com/patternplate/getting-started.git`
  + * Make sure to start patternplate via `pattternplate start` and check it is running on `http://localhost:1337`.
  - Follow along our [Getting Started Guide](./doc/docs/guides/getting-started) to bootstrap one.
  +### Describe a pattern with Markdown
  +
  +Demos for your components are a great way to document them, but some things need additional text docs.
  +
  +E.g. the **Hello World** component has a hidden feature: clicking on it
  +counts up. Let's tell the consumers of our component library about this.
  +
  +1. Open your terminal and create a new file `lib/button/readme.md`
  +
  + ```bash
  + touch lib/hello-world/readme.md
  + ```
  +
  + ```md
  + <!-- lib/hello-world/readme.md -->
  + ## Behaviour
  +
  + Clicking on a the text will count up from 1
  + ```
  +
  +2. Navigate to [localhost:1337/pattern/hello-world](http://localhost:1337/pattern/hello-world?navigation-enabled=true&patterns-enabled=true) and scroll down: Your small description has been rendered below the pattern demo.
  +
  +![](https://patternplate.github.io/media/images/screenshot-doc-pattern-markdown.png)
  +
  +3. Complementy to Markdown you can also provide structured meta data for a pattern, including
  +
  + * **name** - unique identifier for this pattern, e.g. `fancy-button`
  + * **displayName** - human-readable name of the pattern, e.g. `Fancy Button`
  + * **description** - short summary of the pattern intent, e.g. `Primary CTA element for playful contexts`
  + * **version** - the semver version, e.g. `1.0.0`
  + * **flag** - stability flag, one of `alpha`, `beta`, `rc`, `stable`, `deprecated`
  + * **tags** - list of words describing the pattern
  +
  + Meta data for a pattern is saved in `package.json`, e.g. `lib/hello-world/package.json`
  + Copy the following JSON to `lib/hello-world/package.json`:
  +
  + ```json
  + {
  + "name": "hello-world",
  + "version": "2.0.0",
  + "flag": "stable",
  + "tag": ["Getting Started"],
  + "patternplate": {
  + "displayName": "Hello World"
  + }
  + }
  + ```
  +
  + This structured meta data lends itself to indexing nicely and powers much of
  + `patternplate`'s search engine.
  +
  +![](https://patternplate.github.io/media/images/screenshot-doc-pattern-json.png)
  +
  +## Add global documentation
  +
  +You may have noticed the **my-patternplate** item in the Getting Started project:
  +
  +![](https://patternplate.github.io/media/images/screenshot-doc-global.png)
  +
  +This represents the `README.md`, which is picked up by `patternplate` automatically.
  +Click on `my-patternplate` to reveal is rendered contents.
  +
  +Also open a text editor.
  +
  +Having both windows side by side gives you the optimal editing experience:
  +
  +
  +
  +## Related topics
  +
  +* [Documentation](./doc/docs/reference/documentation)
  +* [Demos](./doc/docs/reference/demos)
  