mirror of
https://github.com/gohugoio/hugo.git
synced 2026-09-02 03:32:38 +00:00
Add first round of themes submission guide
This commit is contained in:
Ryan Watters
@@ -1,11 +1,15 @@
|
||||
# Hugo Docs
|
||||
## Hugo Docs POC
|
||||
|
||||
<https://hugodocsconcept.netlify.com>
|
||||
See the concept live at <https://hugodocsconcept.netlify.com>.
|
||||
|
||||
**CURRENTLY IN DEVELOPMENT.** This Hugo Docs concept is a complete reworking of the HUGO documentation. I originally broached the subject of a documentation overhaul here:
|
||||
**CURRENTLY IN DEVELOPMENT.**
|
||||
|
||||
This is *not* a new theme or skin for the [current website](https://gohugo.io). It is a **complete reworking of the Hugo documentation**.
|
||||
|
||||
I originally posed a source reorganization of the current website in this Discuss thread in November 2016 here:
|
||||
|
||||
<https://discuss.gohugo.io/t/proposed-source-organization-for-hugo-docs-concept/4506>
|
||||
|
||||
## Contributing to the Docs
|
||||
I reorganized the docs content and realized it did very little to make the documentation more intelligible or intuitive.
|
||||
|
||||
(WIP) See the guide at <http://gohugo.io/contribute/contribute-to-the-hugo-docs> for instructions on how to contribute to the documentation.
|
||||
So, I'm running with it...
|
||||
@@ -37,7 +37,7 @@ If you make use of the [multilingual feature](/content-management/multilingual/)
|
||||
|
||||
A menu entry has the following properties (i.e., variables) available to it:
|
||||
|
||||
{{< readfile file="readfile-content/menuvars.md" markdown="true" >}}
|
||||
{{< readfile file="readfiles/menuvars.md" markdown="true" >}}
|
||||
|
||||
## Adding content to menus
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Contribute to Hugo development and documentation.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [contribute to hugo]
|
||||
categories: [contribute]
|
||||
tags: []
|
||||
weight: 01
|
||||
draft: false
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Hugo relies heavily on contributions from the open source community
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [contribute to hugo]
|
||||
categories: [contribute]
|
||||
tags: [dev,open source]
|
||||
authors: [digitalcraftsman]
|
||||
weight: 10
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Documentation is an integral part of any open source project. The H
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [contribute to hugo]
|
||||
categories: [contribute]
|
||||
tags: [docs,documentation,community, contribute]
|
||||
weight: 20
|
||||
draft: false
|
||||
|
||||
@@ -5,65 +5,79 @@ description: If you've built a Hugo theme and want to contribute back to the Hug
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-27
|
||||
categories: [contribute to hugo]
|
||||
categories: [contribute]
|
||||
tags: [contribute,themes,design]
|
||||
authors: [digitalcraftsman]
|
||||
weight: 10
|
||||
draft: false
|
||||
aliases: [/contribute/theme/]
|
||||
wip: true
|
||||
notesforauthors:
|
||||
toc: true
|
||||
---
|
||||
|
||||
# Hugo themes
|
||||
A collection of all themes created by the Hugo community, including screenshots and demos, can be found at <https://themes.gohugo.io>. Every theme in this list will automatically be added to the theme site. Theme updates aren't scheduled but usually happen at least once a week.
|
||||
|
||||
A collection of all themes that were created by the Hugo community. See a complete listing of all of these themes along with screenshots and demos at [themes.gohugo.io](http://themes.gohugo.io/). Every theme in this list will automatically be added to the theme site. Theme updates aren't scheduled but usually happen at least once a week.
|
||||
## tl;dr
|
||||
|
||||
## Build script
|
||||
1. Create your theme using `hugo new theme <THEMENAME>`;
|
||||
2. Test your theme against <https://github.com/spf13/HugoBasicExample> \*
|
||||
3. Add a `theme.toml` file to the root of the theme with all required metadata
|
||||
4. Add a descriptive `README.md` to the root of the theme source
|
||||
5. Add `/images/screenshot.png` and `/images/tn.png`
|
||||
|
||||
For the curious,
|
||||
[here's how](https://github.com/spf13/hugoThemeSiteScript/blob/master/generateThemeSite.sh)
|
||||
this automatic adding is accomplished.
|
||||
\* If your theme doesn't fit into the `Hugo Basic Example` site, we encourage theme authors to supply a self-contained Hugo site in `/exampleSite`.
|
||||
|
||||
# Installation
|
||||
{{% note %}}
|
||||
The folder name here---`exampleSite`---is important, as this folder will be picked up and used by the script that generates the Hugo Theme Site. It mirrors the root directory of a Hugo website and allows you to add custom content, assets, and a `config` file with preset values.
|
||||
{{% /note %}}
|
||||
|
||||
## Installing all themes
|
||||
See the [Hugo Artist theme's exampleSite][artistexample] for a good example.
|
||||
|
||||
If you would like to install all of the available Hugo themes, simply clone the entire repository from within your working directory with this command:
|
||||
{{% note %}}
|
||||
Please make your example site's content is as neutral as possible. We hope this goes without saying.
|
||||
{{% /note %}}
|
||||
|
||||
git clone --depth 1 --recursive https://github.com/spf13/hugoThemes.git themes
|
||||
## Theme Requirements
|
||||
|
||||
## Installing a single theme
|
||||
In order to add your theme to the Hugo Themes Showcase, the following requirements need to be met:
|
||||
|
||||
<pre><code>cd themes
|
||||
git clone <em>URL_TO_THEME</em>
|
||||
</code></pre>
|
||||
1. `theme.toml` with all required fields
|
||||
2. Images for thumbnail and screenshot
|
||||
3. A good README file instructions for users
|
||||
4. Added to the hugoThemes GitHub repository
|
||||
|
||||
# Adding a theme to the list
|
||||
### Add Your Theme to the Repo
|
||||
|
||||
* Create your theme using <code>hugo new theme <em>THEMENAME</em></code>;
|
||||
* Test your theme against https://github.com/spf13/HugoBasicExample;
|
||||
* Add a `theme.toml` file to the root of the theme and add some metadata about the theme;
|
||||
* Add a descriptive `README.md` to the root of the theme;
|
||||
* Add `/images/screenshot.png` and `/images/tn.png` (see below);
|
||||
* Open up a new Issue with a link to the theme's repository on GitHub.
|
||||
The easiest way to add your theme is to [open up a new issue in the theme repository][themeissuenew] with a link to the theme's repository on GitHub.
|
||||
|
||||
If your theme doesn't fit into the `Hugo Basic Example` site, we encourage theme authors to supply a self-contained Hugo site in `/exampleSite`.
|
||||
### Create a `theme.toml` File
|
||||
|
||||
**NOTE:** The folder name here is important, as this folder will be picked up and used by the script that generates the Hugo Theme Site. It mirrors the root directory of a Hugo website and allows you to add custom content, assets and a config file with preset values.
|
||||
`theme.toml` contains metadata about the theme and its creator and should be created automatically when running the `hugo new theme`. The auto-generated file is provided here as well for easy downloading:
|
||||
|
||||
See [Artist theme's exampleSite](https://github.com/digitalcraftsman/hugo-artists-theme/tree/master/exampleSite) for a good example. And please make the site's content as neutral as possible.
|
||||
{{% code file="theme.toml" download="theme.toml" %}}
|
||||
```toml
|
||||
name = ""
|
||||
license = "MIT"
|
||||
licenselink = "https://github.com/<YOURNAME>/<YOURTHEME>/blob/master/LICENSE.md"
|
||||
description = ""
|
||||
homepage = "http://yoursite.com/"
|
||||
tags = []
|
||||
features = []
|
||||
min_version = 0.19
|
||||
|
||||
Each theme needs:
|
||||
[author]
|
||||
name = ""
|
||||
homepage = ""
|
||||
|
||||
1. To be added to the hugoThemes repo;
|
||||
1. To have the right fields in `theme.toml`;
|
||||
1. To have the right images; and
|
||||
1. A good README.
|
||||
# If porting an existing theme
|
||||
[original]
|
||||
name = ""
|
||||
homepage = ""
|
||||
repo = ""
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
## theme.toml
|
||||
|
||||
This file contains metadata about the theme and its creator. The following fields are required:
|
||||
The following fields are required:
|
||||
|
||||
```toml
|
||||
name = "Hyde"
|
||||
@@ -72,7 +86,7 @@ licenselink = "https://github.com/spf13/hyde/blob/master/LICENSE.md"
|
||||
description = "An elegant open source and mobile first theme"
|
||||
homepage = "http://siteforthistheme.com/"
|
||||
tags = ["blog", "company"]
|
||||
features = ["blog", ]
|
||||
features = ["blog"]
|
||||
min_version = 0.13
|
||||
|
||||
[author]
|
||||
@@ -86,37 +100,50 @@ min_version = 0.13
|
||||
repo = "https://www.github.com/mdo/hyde"
|
||||
```
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> 1. This is different from the file created by `hugo new theme` in the old v0.12.
|
||||
> The current Hugo v0.13 does create the same template with the new fields
|
||||
> except `min_version` that was added in 0.14-DEV.
|
||||
>
|
||||
> 2. Only `theme.toml` is accepted, not `theme.yaml` or not `theme.json`.
|
||||
{{% note %}}
|
||||
1. This is different from the `theme.toml` file created by `hugo new theme` in Hugo versions before v0.14.
|
||||
2. Only `theme.toml` is accepted; ie. not `theme.yaml` andnot `theme.json`.
|
||||
{{% /note %}}
|
||||
|
||||
### Images
|
||||
|
||||
## Media
|
||||
|
||||
Screenshots are used as preview in the list. Make sure that they have the right dimensions:
|
||||
Screenshots are used for previews in the Hugo Theme Gallery. Make sure that they have the right dimensions:
|
||||
|
||||
* Thumbnail should be 900×600 in pixels
|
||||
* Screenshot should be 1500×1000 in pixels
|
||||
* Media must be located in:
|
||||
* <code><em>[ThemeDir]</em>/images/screenshot.png</code>
|
||||
* <code><em>[ThemeDir]</em>/images/tn.png</code>
|
||||
* <THEMEDIR>/images/screenshot.png</code>
|
||||
* <THEMEDIR>/images/tn.png</code>
|
||||
|
||||
Additional media may be provided in that same directory.
|
||||
Additional media may be provided in the same directory.
|
||||
|
||||
## README.md
|
||||
### Create a README File
|
||||
|
||||
Your theme's README file
|
||||
(which should be written in Markdown and called `README.md`)
|
||||
serves a double purpose.
|
||||
This is because its content will appear in two places—i.e., it will appear:
|
||||
Your theme's README file should be written in markdown and saved at the root of your theme's directory structure. Your `README.md` serves as
|
||||
|
||||
1. On your theme's details page at [themes.gohugo.io](http://themes.gohugo.io/); and
|
||||
1. At GitHub (as usual), on your theme's regular main page.
|
||||
1. Content for your theme's details page at <https://themes.gohugo.io>
|
||||
2. General information about the theme in your GitHub repository (i.e., it's usual purpose)
|
||||
|
||||
{{% note "Screenshots"%}}
|
||||
#### Example `README.md`
|
||||
|
||||
You can download the following `README.md` as an outline:
|
||||
|
||||
{{% code file="README.md" download="README.md" %}}
|
||||
```markdown
|
||||
|
||||
# Theme Title
|
||||
|
||||
**Need input from @digitalcraftsman on what could be added to this file.**
|
||||
|
||||
|
||||
|
||||
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
{{% note "Screenshots in your `README.md`"%}}
|
||||
If you add screenshots to the README, please make use of absolute file paths instead of relative ones like `/images/screenshot.png`. Relative paths work great on GitHub but they don't correspond to the directory structure of [themes.gohugo.io](http://themes.gohugo.io/). Therefore, browsers will not be able to display screenshots on the theme site under the given (relative) path.
|
||||
{{% /note %}}
|
||||
{{% /note %}}
|
||||
|
||||
[artistexample]: https://github.com/digitalcraftsman/hugo-artists-theme/tree/master/exampleSite
|
||||
[themeissuenew]: https://github.com/spf13/hugoThemes/issues/new
|
||||
@@ -18,9 +18,11 @@ Know of a Hugo-related starter kit that isn't mentioned here? [Please add it to
|
||||
The following starter kits are developed by active members of the Hugo community. If you find yourself having issues with any of the projects, it's best to file an issue directly with the project's maintainer(s).
|
||||
{{% /note %}}
|
||||
|
||||
* [Victor Hugo][]. Victor Hugo is a Hugo boilerplate for creating truly epic websites using Gulp + Webpack as an asset pipeline. Victor Hugo uses post-css and Babel for CSS and JavaScript, respectively.
|
||||
* [Victor Hugo][]. Victor Hugo is a Hugo boilerplate for creating truly epic websites using Gulp + Webpack as an asset pipeline. Victor Hugo uses post-css and Babel for CSS and JavaScript, respectively, and is actively maintained.
|
||||
* [Blaupause][]. Blaupause is a developer-friendly Hugo starter kit based on Gulp tasks. It comes ES6-ready with several helpers for SVG and fonts and basic structure for HTML, SCSS, and JavaScript.
|
||||
* [hugulp][]. hugulp is a tool to optimize the assets of a Hugo website. The main idea is to recreate the famous Ruby on Rails Asset Pipeline, which minifies, concatenates and fingerprints the assets used in your website.
|
||||
|
||||
[addkit]: https://github.com/spf13/hugo/edit/master/docs/content/developer-tools/starter-kits.md
|
||||
[Blaupause]: https://github.com/fspoettel/blaupause
|
||||
[hugulp]: https://github.com/jbrodriguez/hugulp
|
||||
[Victor Hugo]: https://github.com/netlify/victor-hugo
|
||||
@@ -79,27 +79,27 @@ Here is the templating for our new `readfile` shortcode:
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
This shortcode is [also part of the Hugo docs][readfilesource]. The Hugo docs also include this [`testing.txt`][testfile] file. We can call pass this file into our new `readfile` shortcode as follows:
|
||||
This shortcode is [also part of the Hugo docs][readfilesource]. The Hugo docs also includes this [`testing.txt`][testfile] file in a `readfiles` directory. We can call pass this file into our new `readfile` shortcode as follows:
|
||||
|
||||
```
|
||||
{{</* readfile file="testing.txt" */>}}
|
||||
{{</* readfile file="readfiles/testing.txt" */>}}
|
||||
```
|
||||
|
||||
The output "string" for calling this file is as follows:
|
||||
|
||||
```markdown
|
||||
{{< readfile file="testing.txt" >}}
|
||||
{{< readfile file="readfiles/testing.txt" >}}
|
||||
```
|
||||
|
||||
However, if we want Hugo to pass this string through Blackfriday, we should add the `markdown="true"` optional parameter:
|
||||
|
||||
```html
|
||||
{{</* readfile file="testing.txt" markdown="true" */>}}
|
||||
{{</* readfile file="readfiles/testing.txt" markdown="true" */>}}
|
||||
```
|
||||
|
||||
And here is it is [called directly in the Hugo docs][] content file used to creat this page and rendered for display:
|
||||
|
||||
{{< readfile file="testing.txt" markdown="true">}}
|
||||
{{< readfile file="readfiles/testing.txt" markdown="true">}}
|
||||
|
||||
[called directly in the Hugo docs]: https://github.com/spf13/hugo/blob/master/docs/content/templates/local-file-templates.md
|
||||
[dirindex]: https://github.com/spf13/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
# readdirs Directory for Reusable Content
|
||||
|
||||
Files in this directory are:
|
||||
|
||||
1. Used in *more than one place* within the Hugo docs
|
||||
2. Used in Examples of readdir (i.e. in local file templates)
|
||||
|
||||
These files are called using the [`readfile` shortcode (source)](../layouts/readfile.html).
|
||||
|
||||
You can call this shortcode in the docs as follows:
|
||||
|
||||
```
|
||||
{{% readfile file="path/to/file.txt" markdown="true" %}}
|
||||
```
|
||||
|
||||
`markdown="true"` is optional (default = `"false"`) and parses the string through the Blackfriday renderer.
|
||||
Vendored
+1
-1
File diff suppressed because one or more lines are too long
@@ -1,5 +1,7 @@
|
||||
|
||||
//Config
|
||||
$usefontawesome: true;
|
||||
|
||||
//Media Query Values
|
||||
$S:480px;
|
||||
$SM: 560px;
|
||||
@@ -19,24 +21,22 @@ $hugo-blue-ultra-light:#D1F1FE;
|
||||
$hugo-yellow:#FCD804;
|
||||
$hugo-gold:#EBB951;
|
||||
$hugo-gray:#737373;
|
||||
$hugo-gray-dark:darken($hugo-gray,10%);
|
||||
$hugo-gray-light:lighten($hugo-gray,30%);
|
||||
$hugo-gray-ultra-light:lighten($hugo-gray-light,23%);
|
||||
$hugo-gray-dark:darken($hugo-gray, 10%);
|
||||
$hugo-gray-light:lighten($hugo-gray, 30%);
|
||||
$hugo-gray-ultra-light:lighten($hugo-gray-light, 23%);
|
||||
$hugo-green:#00A88A;
|
||||
$hugo-green-light:#33BA91;
|
||||
|
||||
//Examples
|
||||
$examplesite-example-color:$hugo-pink;
|
||||
$examplesite-codeblock-shortcode-header-bg-color: $hugo-pink;
|
||||
$input-example-color:$hugo-gray-dark;
|
||||
$output-example-color:$hugo-blue;
|
||||
|
||||
//Document Body
|
||||
$body-bg-color:$hugo-white;
|
||||
|
||||
//Typography
|
||||
$base-font-size: 18px;
|
||||
$base-font-family: 'muli',$helvetica;
|
||||
$base-font-family: 'muli',
|
||||
$helvetica;
|
||||
$heading-font-family: $base-font-family;
|
||||
$base-font-color: #222222;
|
||||
$base-line-height-content: 1.6;
|
||||
@@ -44,21 +44,34 @@ $base-font-weight: 300;
|
||||
$base-font-bold-weight: 600;
|
||||
$base-font-bold-color: $base-font-color;
|
||||
$heading-font-weight: 800;
|
||||
$systemfonts: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen,Ubuntu,Cantarell,"Fira Sans","Droid Sans","Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbols";
|
||||
|
||||
$systemfonts: -apple-system,
|
||||
BlinkMacSystemFont,
|
||||
"Segoe UI",
|
||||
Roboto,
|
||||
Oxygen,
|
||||
Ubuntu,
|
||||
Cantarell,
|
||||
"Fira Sans",
|
||||
"Droid Sans",
|
||||
"Helvetica Neue",
|
||||
Arial,
|
||||
sans-serif,
|
||||
"Apple Color Emoji",
|
||||
"Segoe UI Emoji",
|
||||
"Segoe UI Symbols";
|
||||
//Anchors (in body copy)
|
||||
$default-anchor-color:$base-font-color;
|
||||
$default-anchor-underline-color:$hugo-pink;
|
||||
$default-anchor-weight: $base-font-weight;
|
||||
$active-color: $default-anchor-color;
|
||||
|
||||
//Buttons
|
||||
$base-button-color: $hugo-blue;
|
||||
$base-button-text-color: $hugo-white;
|
||||
$button-border-radius: .25em;
|
||||
|
||||
//Codeblocks
|
||||
$code-font-family:'courierprime',courier,monospace;
|
||||
$code-font-family:'courierprime',
|
||||
courier,
|
||||
monospace;
|
||||
$code-tooltip-bg-color: $hugo-pink;
|
||||
$code-block-base-font-color: #ffffff;
|
||||
$code-block-background-color: $hugo-black;
|
||||
@@ -69,7 +82,6 @@ $code-copy-button-text-color:$base-font-color;
|
||||
$code-base-font-color:$hugo-pink-light;
|
||||
$inline-code-text-color:$base-font-color;
|
||||
$inline-code-background-color:$hugo-gray-ultra-light;
|
||||
|
||||
//Sidebar & Breadcrumb
|
||||
$site-navigation-width: 280px;
|
||||
$content-max-width: 32em;
|
||||
@@ -77,23 +89,18 @@ $site-navigation-bg-color:$hugo-gray-ultra-light;
|
||||
$breadcrumb-navigation-bg-color:$hugo-blue-ultra-light;
|
||||
$breadcrumb-navigation-bg-color-active:$hugo-blue;
|
||||
$breadcrumb-navigation-text-color-active:$hugo-white;
|
||||
|
||||
//Headers
|
||||
$site-header-height:50px;
|
||||
|
||||
//Toc
|
||||
$toc-bg-color:$body-bg-color;
|
||||
|
||||
//Footers
|
||||
$site-footer-bg-color:$hugo-black;
|
||||
$site-footer-height: 100px;
|
||||
|
||||
//Tags
|
||||
$tag-bg-color:$hugo-gray-ultra-light;
|
||||
|
||||
//Brand Colors:
|
||||
$html: #E44D26;
|
||||
$css: #1758A7;
|
||||
$sass: #CF649A;
|
||||
$golang: #69D7E2;
|
||||
$javascript: #F0DB4F;
|
||||
$javascript: #F0DB4F;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
@include fonts('muli', $weights: 100 300 400 600 700 800, $italic: true);
|
||||
@include fonts('courierprime', $weights: 400 700, $italic: true);
|
||||
|
||||
h1,
|
||||
h2,
|
||||
h3,
|
||||
|
||||
Reference in New Issue
Block a user