cupper-hugo-theme/content/patterns/writing/project-structure.md

53 lines
2.2 KiB
Markdown
Raw Normal View History

2017-06-27 21:15:38 +02:00
+++
2017-09-07 10:31:52 +02:00
title = "Project structure"
2017-06-28 11:34:21 +02:00
weight = 1
2017-06-27 21:15:38 +02:00
+++
2017-09-06 21:13:09 +02:00
Before you can set about making documentation, you need to know where everything goes. The simplest folder structure looks like this:
2017-06-27 21:15:38 +02:00
2017-07-16 17:49:20 +02:00
{{% fileTree %}}
* content
* \_index.md
2017-07-29 23:54:56 +02:00
* print-version.md
2017-07-16 17:49:20 +02:00
* patterns
* name-of-my-pattern.md
* name-of-my-other-pattern.md
{{% /fileTree %}}
2017-06-27 21:15:38 +02:00
2017-06-28 11:34:21 +02:00
* **/content** - This is where all of your content lives. You won't need to visit any other folders very frequently.
2017-07-29 23:54:56 +02:00
* **_index.md** — This is the content file for your home page.
* **print-version.md** — This is a placeholder for the single-page / print-friendly version of you library. Leave this file as it is.
2017-11-02 16:37:06 +01:00
* **/patterns** — This is the folder where individual content files are kept. **Cupper** refers to each individual documentation file/page as a "pattern".
2017-06-27 21:15:38 +02:00
## Subsections
2017-11-02 16:37:06 +01:00
You may have noticed that this site's navigation is divided partly into subsections, with labels like "Writing". **Cupper** (or, rather, Hugo) allows you to create such subsections by simply nesting folders under the `/patterns` folder. In the following example, I have a subsection about different types of "popup" pattern.
2017-06-27 21:15:38 +02:00
2017-07-16 17:49:20 +02:00
{{% fileTree %}}
* content
* \_index.md
* patterns
* name-of-my-pattern.md
* name-of-my-other-pattern.md
* popups
* \_index.md
* popup-menu.md
* tooltips.md
{{% /fileTree %}}
2017-06-27 21:15:38 +02:00
2017-09-12 16:19:26 +02:00
Subfolders like `/popups` must each have an `_index.md` file. This file doesn't need any content except the TOML metadata defining the title (name) of that subsection:
2017-06-27 21:15:38 +02:00
```
+++
2017-09-12 16:31:15 +02:00
title = "Popup windows"
2017-06-27 21:15:38 +02:00
+++
```
2017-09-12 16:37:19 +02:00
This title is what labels the subsection in the navigation, *not* the folder name (`/popups`, in this case). For each subfolder you create, you must also create one of these `_index.md` files. The `/patterns` folder itself does not need one, however.
2017-06-27 21:15:38 +02:00
2017-09-12 16:19:26 +02:00
{{% note %}}
2017-11-02 16:37:06 +01:00
**Cupper** does not currently support _sub_-subsections. You can only create child folders under `/patterns`.
2017-06-27 21:15:38 +02:00
{{% /note %}}
2017-06-28 11:34:21 +02:00
Now that you know where to put everything, it's time to talk about how to actually write individual patterns. Don't worry, it's pretty straightforward. Turn to {{% pattern "Markdown & metadata" %}}.