cupper-hugo-theme/content/patterns/library-setup.md

70 lines
3.9 KiB
Markdown
Raw Normal View History

2017-06-27 21:15:38 +02:00
+++
title = "Library setup"
2017-08-02 10:23:48 +02:00
weight = 2
2017-06-27 21:15:38 +02:00
+++
2017-06-28 11:34:21 +02:00
By now, you should have followed the {{% pattern "Installation" %}} instructions. You should have Hugo and Node installed, and a local copy of a forked version of **Infusion**. You should also have run `npm install` in the root of that codebase.
2017-06-27 21:15:38 +02:00
## "Cleaning" the content folder
Before you can start documenting patterns, there are a few things still to do in order to get set up. At the moment, your version of **Infusion** is a facsimile of the original, containing all this documentation content. We want to delete that content and replace it with some starter content. There's a simple `clean` command for this.
{{% warning %}}
If you are contributing to an existing **Infusion** library, do not run the following command. It will delete all of the patterns in that library. The `clean` command is just for libraries that you are starting from scratch.
{{% /warning %}}
2017-07-15 10:28:17 +02:00
{{<cmd>}}
npm run clean
{{</cmd>}}
2017-06-27 21:15:38 +02:00
2017-06-28 11:34:21 +02:00
This will leave your `content` folder with just an `_index.md` file and a `patterns` folder containing a single demonstration pattern file. Find out more about these in {{% pattern "Library structure" %}}.
2017-06-27 21:15:38 +02:00
## The config file
You'll also want to name your library and configure one or two other things in the `config.toml` file that's found at the root of your project. Here's how that file looks:
{{<codeBlock lang="html" numbered="true">}}
languageCode = "en-us"
2017-07-03 12:42:10 +02:00
title = "Infusion"
baseURL = "https://heydon.github.io/infusion/"
2017-06-27 21:15:38 +02:00
theme = "infusion"
[params]
2017-07-10 20:53:24 +02:00
description = "Documentation for the **Infusion** pattern library builder. This documentation is constructed using the builder itself."
2017-06-27 21:15:38 +02:00
codePenUser = "Heydon"
{{</codeBlock>}}
2017-07-03 21:02:40 +02:00
* **title** — This is the library's name, like "Megacorp 5000 Pattern Library". You don't have to include the term "pattern library" if you don't want to. For **Infusion's** own version of **Infusion**, the `title` is, naturally, _Infusion_ :-)
* **baseURL** — This is the root of the live site. Typically you will publish the site to Github Pages, so this should be the base URL for your Github Pages site.
2017-06-27 21:15:38 +02:00
* **theme** — This is the theme the library is using. Don't change this from "infusion".
2017-07-10 20:53:24 +02:00
* **description** — This is a short description of the library and comes under the logo. You can include markdown syntax here, like _&#x002a;&#x002a;Infusion&#x002a;&#x002a;_ in the above example for making the name of the library bold.
2017-06-27 21:15:38 +02:00
* **codePenUser** — If you want to embed codePens in your pattern files, you need to supply a codePen username here.
2017-08-02 21:57:01 +02:00
## The Web App Manifest
**Infusion** libraries work as progressive web applications, meaning users can save them to their home screen and read them offline. The web app manifest, found at the root of the `static` folder defines names and icons for the app. You'll probably want to open `/static/manifest.json` and personalize the `name` and `short_name` values.
```
{
2017-08-03 15:55:45 +02:00
"name": "Infusion Pattern Library Docs",
"short_name": "Infusion Docs",
2017-08-02 21:57:01 +02:00
"icons": [
{...
```
{{% note %}}
2017-08-03 15:55:45 +02:00
The `short_name` value refers to the text that appears under the icon on your homescreen. As the name suggests, it should be as short as possible to fit well.
2017-08-02 21:57:01 +02:00
{{% /note %}}
2017-06-27 21:15:38 +02:00
## Including a logo
2017-08-02 19:00:38 +02:00
In the `images/static` folder, you'll find a `logo.svg` file. Replace this file with your own company or project logo. Currently, only the SVG is supported this easily because SVG the superior format for logotypes. However, if you must use a different format, you can open up the `themes/infusion/layouts/_default/baseof.html` file and edit the image reference:
```html
<a class="logo" href="/" aria-label="{{ .Site.Title }} pattern library home page">
<img src="{{ "images/logo.svg" | absURL }}" alt="">
</a>
```
2017-06-27 21:15:38 +02:00
2017-06-28 11:34:21 +02:00
Now that your logo's in place, everything should be ready. Where next? You can learn about {{% pattern "Library structure" %}} to help you get writing, or find out how to serve the library locally and on Github Pages in {{% pattern "Serving" %}}.