blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-31 02:32:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update archetypes section

Browse Source
This commit is contained in:
Ryan Watters
2017-02-11 16:31:35 -08:00
parent f9db26c544
commit c18d21d8ad
11 changed files with 111 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/content-management/archetypes.md
+24 -24
View File
@@ -7,14 +7,16 @@ publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [archetypes,generators]
categories: [content]
weight: 50
weight:
draft: false
slug:
aliases: []
notes:
---
Hugo uses **archetypes** to facilitate creation of consistent metadata for content types across a website. Authors can use the the `hugo new` command combined with the file path from the [`content`][], an author could create an empty content file, with the date and title automatically defined in the front matter of the post. While this was a welcome feature, active writers need more flexibility.
Hugo uses **archetypes** to facilitate creation of consistent metadata for content types across a website. Archetypes allow authors to easily generate new content files with associated metadata that are new instances of a content type. {{< relref "content-management/front-matter.md" >}}
To create new instances of a content type that pull from an archetype, authors can use the the `hugo new` command combined with the file path from the [content][] downward; e.g.---
```bash
hugo new posts/my-first-post.md
@@ -24,13 +26,9 @@ When defining a custom content type, you can use an **archetype** as a way to
define the default metadata for a new post of that type.
**Archetypes** are quite literally archetypal content files with pre-configured
[front matter][]. An archetype will populate each new
content file of a given type with any default metadata you've defined whenever
you run the `hugo new` command.
[front matter][]. An archetype will populate each new content file of a given type with any default metadata you've defined whenever you run the `hugo new` command.
## Example
### 1. Creating an archetype
## Creating an archetype
In the following example scenario, suppose we have a blog with a single content
type (blog post). Our imaginary blog will use ‘tags’ and ‘categories’ for its
@@ -47,10 +45,10 @@ categories = ["x", "y"]
{{% /input %}}
{{% caution ""%}}
Some editors (e.g., Sublime, Emacs) do not insert an EOL (end-of-line) character at the end of the file (i.e. EOF). If you get a [strange EOF error](/troubleshooting/strange-eof-error/) when using `hugo new`, please open each archetype file (i.e.&nbsp;`archetypes/*.md`) and press <kbd>Enter</kbd> to type a carriage return after the closing `+++` or `---` as necessary.
Some editors (e.g., Sublime, Emacs) do not insert an end-of-line (EOL) character at the end of the file (EOF). If you get a [strange EOF error](/troubleshooting/frequently-asked-questions/#eof-error) when using `hugo new`, open each archetype file and press <kbd>Enter</kbd> to type a carriage return after the closing `+++` or `---` if you're using TOML or YAML front matter, respectively.
{{% /caution %}}
### 2. Using the archetype
## Using the archetype
Now, with `archetypes/default.md` in place, let's create a new post in the `post`
section with the `hugo new` command:
@@ -70,16 +68,16 @@ categories = ["x", "y"]
```
{{% /output %}}
We see that the `title` and `date` variables have been added, in addition to the `tags` and `categories` variables which were carried over from `archetype/default.md`.
We see that the `title` and `date` variables have been added in addition to the `tags` and `categories` variables that were carried over from `archetype/default.md`.
Congratulations! We have successfully created an archetype and used it to
quickly scaffold out a new post. But wait, what if we want to create some content that isn't exactly a blog post, like a profile for a musician? Let's see how using **archetypes** can help us out.
### Creating custom archetypes
## Creating custom archetypes
Previously, we had created a new content type by adding a new subfolder to the content directory. In this case, its name would be `content/musician`. To begin using a `musician` archetype for each new `musician` post, we simply need to create a file named after the content type called `musician.md`, and put it in the `archetypes` directory, similar to the one below.
#### archetypes/musician.md
## archetypes/musician.md
```toml
+++
@@ -91,11 +89,14 @@ genre = ""
Now, let's create a new musician.
$ hugo new musician/mozart.md
```bash
$ hugo new musician/mozart.md
```
This time, Hugo recognizes our custom `musician` archetype and uses it instead of the default one. Take a look at the new `musician/mozart.md` post. You should see that the generated file's front matter now includes the variables `name`, `bio`, and `genre`.
#### content/musician/mozart.md
{{% output "content/musician/mozart.md" %}}
```toml
+++
@@ -106,15 +107,13 @@ bio = ""
genre = ""
+++
```
{{% /output %}}
## Using a different front matter format
## Using a Different Front Matter Format
By default, the front matter will be created in the TOML format
regardless of what format the archetype is using.
By default, the front matter will be created in the TOML format regardless of what format the archetype is using.
You can specify a different default format in your site-wide config file
(e.g. `config.toml`) using the `MetaDataFormat` directive.
Possible values are `"toml"`, `"yaml"` and `"json"`.
You can specify a different default format in your site [configuration file][] file using the `metaDataFormat` directive. Possible values are `toml`, `yaml`, and `json`.
## Which archetype is being used
@@ -139,17 +138,18 @@ provides an archetype. This is by design---the rationale is that the archetype s
The content type is automatically detected based on the file path passed to the
Hugo CLI command:
```toml
```bash
hugo new [my-content-type/post-name]
```
To override the content type for a new post, include the `--kind` flag during creation.
{{% note "Using Theme Archetypes" %}}
If you wish to use archetypes that ship with a theme, the theme be specified in your [`config`](/project-organization/configuration/) file.
If you wish to use archetypes that ship with a theme, the theme be specified in your [configuration file](/project-organization/configuration/).
{{% /note %}}
[front matter]: /content-management/front-matter/
[`content`]: /project-organization/directory-structure/
[content]: /project-organization/directory-structure/
[configuration file]: /project-organization/configuration/
[`now()`]: http://golang.org/pkg/time/#Now
content/content-management/content-types.md
+15
View File
@@ -0,0 +1,15 @@
---
title: Content Types
linktitle:
description:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: []
categories: []
weight:
draft: false
slug:
aliases: []
notes:
---
content/troubleshooting/_index.md
+1
View File
@@ -5,6 +5,7 @@ description: FAQs pulled from the Hugo forum, known issues, and workarounds.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
layout: singlescroller
weight: 01
draft: false
slug:
content/troubleshooting/frequently-asked-questions.md
-14
View File
@@ -1,14 +0,0 @@
---
title: Frequently Asked Questions
linktitle:
description: Description for *troubleshooting* section.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
weight:
draft: false
slug:
aliases: [/troubleshooting/faqs]
notes:
---
eof-error.md
+49
View File
@@ -0,0 +1,49 @@
---
title: EOF Error
linktitle:
description: Description for *troubleshooting* section.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
weight:
draft: false
slug:
aliases: [/troubleshooting/faqs]
notes:
---
## `hugo new` Aborts with a Cryptic EOF Error
> I'm running into an issue where I cannot get archetypes working, when running `hugo new showcase/test.md`, for example, I see an `EOF` error thrown by Hugo.
>
> I have set up this test repository to show exactly what I've done, but it is essentially a vanilla installation of Hugo. https://github.com/polds/hugo-archetypes-test
>
> When in that repository, using Hugo v0.12 to run `hugo new -v showcase/test.md`, I see the following output:
>
> INFO: 2015/01/04 Using config file: /private/tmp/test/config.toml
> INFO: 2015/01/04 attempting to create showcase/test.md of showcase
> INFO: 2015/01/04 curpath: /private/tmp/test/archetypes/showcase.md
> ERROR: 2015/01/04 EOF
>
> Is there something that I am blatantly missing?
## Solution
Thank you for reporting this issue. The solution is to add a final newline (i.e. EOL) to the end of your default.md archetype file of your theme. More discussions happened on the forum here:
* http://discuss.gohugo.io/t/archetypes-not-properly-working-in-0-12/544
* http://discuss.gohugo.io/t/eol-f-in-archetype-files/554
Due to popular demand, Hugo's parser has been enhanced to
accommodate archetype files without final EOL,
thanks to the great work by [@tatsushid](https://github.com/tatsushid),
in the upcoming v0.13 release,
Until then, for us running the stable v0.12 release, please remember to add the final EOL diligently. <i class="fa fa-smile-o"></i>
## References
* https://github.com/spf13/hugo/issues/776
themes/hugodocs/layouts/_default/singlescroller.html
+2
View File
@@ -0,0 +1,2 @@
{{ define "main" }}
{{ end }}
themes/hugodocs/pipeline/scss/_variables.scss
+3 -1
View File
@@ -55,7 +55,9 @@ $code-editor-header-bg-color: $hugo-gray-dark;
$code-filename-color:#ffffff;
$code-copy-button-color:#ffffff;
$code-copy-button-text-color:$base-font-color;
$inline-code-text-color:$hugo-pink-light;
$code-base-font-color:$hugo-pink-light;
$inline-code-text-color:$base-font-color;
$inline-code-background-color:lighten($hugo-gray-light,15%);
//Sidebar
$site-navigation-width: 280px;
themes/hugodocs/pipeline/scss/components/_code.scss
+6 -132
View File
@@ -3,6 +3,7 @@ code,
pre {
font-family: $code-font-family;
margin: 0px;
color:$code-base-font-color;
}
.body-copy > pre {
@@ -17,19 +18,20 @@ pre {
p {
code {
display:inline-block;
padding-top:.15em;
}
}
}
p code,
li > code {
li code {
font-size: .9em;
color: $inline-code-text-color;
font-family: $code-font-family;
border: 1px solid $hugo-gray-light;
// border: 1px solid $hugo-gray-light;
padding-left: .25em;
padding-right: .25em;
background-color: $code-block-background-color;
background-color: $inline-code-background-color;
border:none;
outline:none;
}
@@ -332,132 +334,4 @@ div.code-copy-header {
.tooltipped-multiline.tooltipped-w:after,
.tooltipped-multiline.tooltipped-e:after {
right: 100%
}
// /* Modified heavily from http://prismjs.com/download.html?themes=prism&languages=markup+css+clike+javascript+go+markdown+scss&plugins=line-numbers */
// /**
// * prism.js default theme for JavaScript, CSS and HTML
// * Based on dabblet (http://dabblet.com)
// * @author Lea Verou
// */
// code[class*="language-"],
// pre[class*="language-"] {
// color: $code-block-base-font-color;
// background-color:$code-block-background-color;
// text-shadow: none;
// font-family: $code-font-family;
// text-align: left;
// white-space: pre;
// word-spacing: normal;
// word-break: normal;
// word-wrap: normal;
// line-height: 1.7;
// tab-size: 2;
// hyphens: none;
// }
// pre[class*="language-"]::-moz-selection,
// pre[class*="language-"]::-moz-selection,
// code[class*="language-"]::-moz-selection,
// code[class*="language-"]::-moz-selection {
// text-shadow: none;
// background: $hugo-blue-light;
// }
// pre[class*="language-"]::selection,
// pre[class*="language-"]::selection,
// code[class*="language-"]::selection,
// code[class*="language-"]::selection {
// text-shadow: none;
// background: $hugo-blue-light;
// }
// @media print {
// code[class*="language-"],
// pre[class*="language-"] {
// text-shadow: none;
// }
// }
// /* Code blocks */
// pre[class*="language-"],
// code[class*="language-"] {
// padding: 1em 1em 2em 1em;
// margin: 0;
// overflow: auto;
// background-color: $code-block-background-color;
// }
// /* Inline code */
// :not(pre) > code[class*="language-"] {
// padding: .1em;
// border-radius: .3em;
// white-space: normal;
// }
// .token.comment,
// .token.prolog,
// .token.doctype,
// .token.cdata {
// color: $hugo-gray-dark;
// }
// .token.punctuation {
// color: #999;
// }
// .namespace {
// opacity: .7;
// }
// .token.property,
// .token.tag,
// .token.boolean,
// .token.number,
// .token.constant,
// .token.symbol,
// .token.deleted {
// color: $hugo-pink;
// }
// .token.selector,
// .token.attr-name,
// .token.string,
// .token.char,
// .token.builtin,
// .token.inserted {
// color: $hugo-green;
// }
// .token.operator,
// .token.entity,
// .token.url,
// .language-css .token.string,
// .style .token.string {
// color: $hugo-pink;
// }
// .token.atrule,
// .token.attr-value,
// .token.keyword {
// color: $hugo-blue;
// }
// .token.function {
// color: $hugo-gold;
// }
// .token.regex,
// .token.important,
// .token.variable {
// color: $hugo-gold
// }
// .token.important,
// .token.bold {
// font-weight: bold;
// }
// .token.italic {
// font-style: italic;
// }
// .token.entity {
// cursor: help;
// }
// // //Modifications,
// // code.language-markdown {
// // span.token.italic {
// // color: $hugo-pink;
// // }
// // span.token.url {
// // color: $hugo-blue;
// // }
// // //for * and 1 in markdown lists
// // .token.list.punctuation {
// // color: $hugo-blue;
// // }
// // }
}
themes/hugodocs/pipeline/scss/components/_keyboard.scss
+9
View File
@@ -0,0 +1,9 @@
kbd {
background-color: inherit;
border:1px solid $base-font-color;
display:inline-block;
font-size:.9em;
padding:.1em .3em;
border-radius:5px;
@include card(1);
}
themes/hugodocs/pipeline/scss/style.scss
+1
View File
@@ -23,6 +23,7 @@
@import 'components/tags';
@import 'algolia/main';
@import 'components/site-search';
@import 'components/keyboard';
//major layout parts/chrome
themes/hugodocs/static/css/style.min.css
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long