github.com/google/cloudprober@v0.11.3/docs/themes/hugo-material-docs/exampleSite/content/getting-started/index.md

github.com/google/cloudprober@v0.11.3/docs/themes/hugo-material-docs/exampleSite/content/getting-started/index.md (about)

1 ---
2 date: 2016-03-09T00:11:02+01:00
3 title: Getting started
4 weight: 10
5 ---
6
7 ## Installation
8
9 ### Installing Hugo
10
11 Hugo itself is just a single binary without dependencies on expensive runtimes like Ruby, Python or PHP and without dependencies on any databases. You just need to download the [latest version](https://github.com/spf13/hugo/releases). For more information read the official [installation guides](http://gohugo.io/overview/installing/).
12
13 Let's make sure Hugo is set up as expected. You should see a similar version number in your terminal:
14
15 ```sh
16 hugo version
17 # Hugo Static Site Generator v0.15 BuildDate: 2016-01-03T12:47:47+01:00
18 ```
19
20 ### Installing Material
21
22 Next, assuming you have Hugo up and running the `hugo-material-docs` theme can be installed with `git`:
23
24 ```sh
25 # create a new Hugo website
26 hugo new site my-awesome-docs
27
28 # move into the themes folder of your website
29 cd my-awesome-docs/themes/
30
31 # download the theme
32 git clone git@github.com:digitalcraftsman/hugo-material-docs.git
33 ```
34
35 ## Setup
36
37 Next, take a look in the `exampleSite` folder at `themes/hugo-material-docs/`. This directory contains an example config file and the content that you are currently reading. It serves as an example setup for your documentation.
38
39 Copy at least the `config.toml` in the root directory of your website. Overwrite the existing config file if necessary.
40
41 Hugo includes a development server, so you can view your changes as you go -
42 very handy. Spin it up with the following command:
43
44 ``` sh
45 hugo server
46 ```
47
48 Now you can go to [localhost:1313](http://localhost:1313) and the Material
49 theme should be visible. You can now start writing your documentation, or read
50 on and customize the theme through some options.
51
52 ## Configuration
53
54 Before you are able to deploy your documentation you should take a few minute to adjust some information in the `config.toml`. Open the file in an editor:
55
56 ```toml
57 baseurl = "https://example.com/"
58 languageCode = "en-us"
59 title = "Material Docs"
60
61 [params]
62 # General information
63 author = "Digitalcraftsman"
64 description = "A material design theme for documentations."
65 copyright = "Released under the MIT license"
66 ```
67
68 ## Options
69
70 ### Github integration
71
72 If your project is hosted on GitHub, add the repository link to the
73 configuration. If the `provider` equals **GitHub**, the Material theme will
74 add a download and star button, and display the number of stars:
75
76 ```toml
77 [params]
78 # Repository
79 provider = "GitHub"
80 repo_url = "https://github.com/digitalcraftsman/hugo-material-docs"
81 ```
82
83 ### Adding a version
84
85 In order to add the current version next to the project banner inside the
86 drawer, you can set the variable `version`:
87
88 ```toml
89 [params]
90 version = "1.0.0"
91 ```
92
93 This will also change the link behind the download button to point to the
94 archive with the respective version on GitHub, assuming a release tagged with
95 this exact version identifier.
96
97 ### Adding a logo
98
99 If your project has a logo, you can add it to the drawer/navigation by defining
100 the variable `logo`. Ideally, the image of your logo should have
101 rectangular shape with a minimum resolution of 128x128 and leave some room
102 towards the edges. The logo will also be used as a web application icon on iOS.
103 Either save your logo somewhere in the `static/` folder and reference the file relative to this location or use an external URL:
104
105 ```toml
106 [params]
107 logo = "images/logo.png"
108 ```
109
110 ### Adding a custom favicon
111
112 Favicons are small small icons that are displayed in the tabs right next to the title of the current page. As with the logo above you need to save your favicon in `static/` and link it relative to this folder or use an external URL:
113
114 ```toml
115 [params]
116 favicon = "favicon.ico"
117 ```
118
119 ### Google Analytics
120
121 You can enable Google Analytics by replacing `UA-XXXXXXXX-X` with your own tracking code.
122
123 ```toml
124 googleAnalytics = "UA-XXXXXXXX-X"
125 ```
126
127 ### Small tweaks
128
129 This theme provides a simple way for making small adjustments, that is changing
130 some margins, centering text, etc. The `custom_css` and `custom_js` option allow you to add further CSS and JS files. They can either reside locally in the `/static` folder or on an external server, e.g. a CDN. In both cases use either the relative path to `/static` or the absolute URL to the external ressource.
131
132
133 ```toml
134 [params]
135 # Custom assets
136 custom_css = [
137 "foo.css",
138 "bar.css"
139 ]
140
141 custom_js = ["buzz.js"]
142 ```
143
144 ### Changing the color palette
145
146 Material defines a default hue for every primary and accent color on Google's
147 material design [color palette][]. This makes it very easy to change the overall look of the theme. Just set the variables `palette.primary` and `palette.accent` to one of the colors defined in the palette:
148
149 ```toml
150 [params.palette]
151 primary = "red"
152 accent = "light-green"
153 ```
154
155 Color names can be written upper- or lowercase but must match the names of the
156 material design [color palette](http://www.materialui.co/colors). Valid values are: _red_, _pink_, _purple_, _deep purple_, _indigo_, _blue_, _light-blue_, _cyan_, _teal_, _green_, _light-green_,
157 _lime_, _yellow_, _amber_, _orange_, _deep-orange_, _brown_, _grey_ and
158 _blue-grey_. The last three colors can only be used as a primary color.
159
160 ![Color palette](/images/colors.png)
161
162 If the color is set via this configuration, an additional CSS file called
163 `palettes.css` is included that defines the color palettes.
164
165 ### Changing the font family
166
167 Material uses the [Ubuntu font family](http://font.ubuntu.com) by default, specifically the regular sans-serif type for text and the monospaced type for code. Both fonts are loaded from [Google Fonts](https://www.google.com/fonts) and can be easily changed to other fonts, like for example Google's own [Roboto font](https://www.google.com/fonts/specimen/Roboto):
168
169 ```toml
170 [params.font]
171 text = "Roboto"
172 code = "Roboto Mono"
173 ```
174
175 The text font will be loaded in font-weights 400 and **700**, the monospaced
176 font in regular weight.
177
178 ### Syntax highlighting
179
180 This theme uses the popular [Highlight.js](https://highlightjs.org/) library to colorize code examples. The default theme is called `Github` with a few small tweaks. You can link our own theme if you like. Again, store your stylesheet in the `static/` folder and set the relative path in the config file:
181
182 ```toml
183 [params]
184 # Syntax highlighting theme
185 highlight_css = "path/to/theme.css"
186 ```
187
188 ### Adding a GitHub and Twitter account
189
190 If you have a GitHub and/or Twitter account, you can add links to your
191 accounts to the drawer by setting the variables `github` and
192 `twitter` respectively:
193
194 ``` toml
195 [social]
196 twitter = ""
197 github = "digitalcraftsman"
198 ```
199
200 ### Adding menu entries
201
202 Once you created your first content files you can link them manually in the sidebar on the left. A menu entry has the following schema:
203
204 ```toml
205 [[menu.main]]
206 name = "Material"
207 url = "/"
208 weight = 0
209 pre = ""
210 ```
211
212 `name` is the title displayed in the menu and `url` the relative URL to the content. The `weight` attribute allows you to modify the order of the menu entries. A menu entry appears further down the more weight you add. The `pre` attribute is optional and allows you to *pre*pend elements to a menu link, e.g. an icon.
213
214 Instead of just linking a single file you can enhance the sidebar by creating a nested menu. This way you can list all pages of a section instead of linking them one by one (without nesting).
215
216 You need extend the frontmatter of each file content file in a section slightly. The snippet below registers this content file as 'child' of a menu entry that already exists.
217
218 ```yaml
219 menu:
220 main:
221 parent: Material
222 identifier: <link name>
223 weight: 0
224 ```
225
226 `main` specifies to which menu the content file should be added. `main` is the only menu in this theme by default. `parent` let's you register this content file to an existing menu entry, in this case the `Material` link. Note that the parent in the frontmatter needs to match the name in `config.toml`.
227
228 `identifier` is the link that is shown in the menu. Ideally you choose the same name for the `identifier` and the `title` of the page. Again, `weight` allows you to change the order of the nested links in a section.
229
230 ### Markdown extensions
231
232 Hugo uses [Blackfriday](https://github.com/russross/blackfriday) to process your content. For a detailed description of all options take a look at the [Blackfriday configuration](http://gohugo.io/overview/configuration/#configure-blackfriday-rendering) section in the Hugo documentation.
233
234 ```toml
235 [blackfriday]
236 smartypants = true
237 fractions = true
238 smartDashes = true
239 plainIDAnchors = true
240 ```