import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="Foundations/Writing Documentation" />

# Writing Documentation

## Quick Links
- [Our stories folder on GitHub](https://github.com/nypublicradio/nypr-design-system/tree/main/stories)
- [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
- [Github Help: Managing Files on GitHub](https://help.github.com/en/github/managing-files-in-a-repository/managing-files-on-github)
- [StackEdit](https://stackedit.io/)
- [MDX Component Template](https://pastebin.com/mX8GGpRb)

## About MDX

Storybook documentation is written in MDX. MDX is a documentation format that lets us write [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) documents but also include live code examples and other components to help make our documentation dynamic. In storybook all our documentation files are named with a `.stories.mdx` extension. The files are included in the document tree in alphabetical order, file and folder names are prefixed with numbers to give us manual control over this sort order. (e.g. `10-Typography.stories.mdx`)

MDX files have a bit of code at the top that looks like something this.

```
import { Meta } from '@storybook/addon-docs/blocks'

<Meta title="Foundations/Typography" />
```

Storybook needs this code to recognize documents and include them in the sidebar.

## About Titles

Titles control what a page is called in the Storybook sidebar as well as where in the documentation hierarchy it is located. A title of "Foundations/Typography" will create an item called "Typography" in the "Foundations" folder.

## Editing Pages in GitHub

When viewing any of the pages within the [/stories](https://github.com/nypublicradio/nypr-design-system/tree/main/stories) folder on GitHub, you can click the pencil icon to edit the file.

This will bring up an editor where you can make changes to the file.  The documentations files use [Markdown formatting](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). There's a Preview Changes tab in this view that will let you check how your Markdown will be rendered.

[More detailed guide to the GitHub editor.](https://help.github.com/en/github/managing-files-in-a-repository/editing-files-in-your-repository)

## Adding Pages in GitHub

From the [/stories](https://github.com/nypublicradio/nypr-design-system/tree/main/stories) folder in GitHub you can click the "Create New File" button to add a new file in any of the folders.

It's fine to copy the markdown from an existing page and base your new page on it.

The file name has to end in `.stories.mdx` or Storybook will ignore it.

We can use filenames to control the order of files in the storybook sidebar. Files are loaded in alphabetical order, so a file named `10-Intro...` will appear above a file named `90-Special Thanks...`.

## Adding A Folder, Renaming Files, Deleting Files

See the [GitHub help page on managing files](https://help.github.com/en/github/managing-files-in-a-repository/managing-files-on-github) for more details.

## Including Images

Add your image to the [/stories/assets/images/](https://github.com/nypublicradio/nypr-design-system/tree/main/stories/assets/images) folder.

Include the image your Markdown like this:
`![alt text](./images/my-image.png)`

If you need to set the size you can use HTML:
`<img alt="alt text" src="./images/my-image.png" width="200" />`

## StackEdit

If you want to prepare documentation outside of GitHub, [StackEdit](https://stackedit.io/) is a browser-base Markdown editor with a realtime preview, and some other handy buttons to make working in Markdown nicer.

If you prefer to work in Google Docs, you can copy and paste your from you Google Doc into StackEdit and it will convert it into Markdown.

When you're ready to add to Storybook, you can copy and paste the Markdown text from StackEdit into GitHub.