blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-25 15:58:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add first draft of strategy statement and content revisions

Browse Source
This commit is contained in:
Ryan Watters
2017-02-21 14:35:54 -06:00
parent f8115778b4
commit 13c75f44ee
12 changed files with 256 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1 -2
View File
@@ -1,4 +1,3 @@
themes/hugodocs/pipeline/node_modules
my-notes.md
notes-for-reviewers.md
features-log.md
notes-for-reviewers.md
README.md
+2 -3
View File
@@ -2,11 +2,10 @@
<https://hugodocsconcept.netlify.com>
**Currently In Development.** This Hugo Docs concept is an attempt at implementing the new docs source organization found here:
**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:
<https://discuss.gohugo.io/t/proposed-source-organization-for-hugo-docs-concept/4506>
## Contributing to the Docs
## Suggestions for Improvements
(WIP) See the guide at <http://gohugo.io/contribute-to-hugo/contribute-to-the-hugo-docs> for instructions on how to contribute to the documentation.
tree.txt → annotated-content-changes.md
+50 -2
View File
@@ -1,3 +1,50 @@
<!-- MarkdownTOC -->
- [Changes to Existing Content Sections][changes-to-existing-content-sections]
- [Extras][extras]
- [Tutorials][tutorials]
- [Content Organization \(Site\)][content-organization-site]
- [Content Organization \(Source\)][content-organization-source]
<!-- /MarkdownTOC -->
<a name="changes-to-existing-content-sections"></a>
## Changes to Existing Content Sections
The following is an *abbreviated* listing and only includes the *larger* changes to content organization
<a name="extras"></a>
### [Extras](http://gohugo.io/extras)
* This section no longer exists in the new documentation site
* *Extras*, in the content world, is the equivalent of *miscellaneous* or *additional resources*. READ: "We don't have any idea of where to put this"
* Previous pages in extras are now in the following locations:
* **Aliases** Incorporated into `/content-management/url-management/`
* **Analytics** Incorporated into /templates/partial-templates/#built-in
<a name="tutorials"></a>
### [Tutorials](http://gohugo.io/tutorials)
* Moved all installation guides to /getting-started/install-hugo/
* Installing Hugo shouldn't be considered a separate tutorial
* "Tutorials" is not an intuitive place for end-users to look for this kind of documentation
* All content moved from `/tutorials` edited to reflect a less tutorial-ish style of language (e.g., remove of lines starting with "In this tutorial...")
* Aliases added to new pages and in-page links updated throughout
<a name="content-organization-site"></a>
## Content Organization (Site)
The following is a list of weights for the newly restructure site architecture
<a name="content-organization-source"></a>
## Content Organization (Source)
**2017-02-21 New Content Reorganization**
```
.
├── _index.md
├── about-hugo
@@ -262,14 +309,14 @@
│   ├── customizing-a-theme.md
│   ├── installing-and-using-themes.md
│   └── theme-showcase.md
├── tree.txt
├── troubleshooting
│   ├── _index.md
│   ├── accented-characters-in-urls.md
│   └── eof-error.md
├── tutorials
│   ├── _index.md
│   ├── creating-a-multilingual-site.md
│   ├── create-a-multilingual-site.md
│   ├── creating-a-new-theme.md
│   └── migrate-from-jekyll-to-hugo.md
└── variables-and-params
├── _index.md
@@ -280,3 +327,4 @@
└── taxonomy-variables.md
15 directories, 264 files
```
content/news/press-and-articles.md
+1
View File
@@ -23,6 +23,7 @@ Hugo has been featured in the following Blog Posts, Press, and Media.
| Title | Author | Date |
| ----- | ------ | -----: |
| [How to Password Protect a Hugo Site](https://www.aerobatic.com/blog/password-protect-a-hugo-site/) | Aerobatic | 2017-02-19 |
| [Switching from Wordpress to Hugo](http://schnuddelhuddel.de/switching-from-wordpress-to-hugo/) | http://schnuddelhuddel.de/ | 2017-02-19 | ]
| [Deploy a Hugo site to Aerobatic with CircleCI ](https://www.aerobatic.com/blog/hugo-github-circleci/) | Aerobatic | 2017-02-14 |
| [NPM scripts for building and deploying Hugo site]() | Aerobatic | 2017-02-12 |
| [Build a Hugo site using Cloud9 IDE and host on App Engine](https://loyall.ch/lab/2017/01/build-a-static-website-with-cloud9-hugo-and-app-engine/)| Pascal Aubort | 2017-02-05 |
content/templates/partial-templates.md
+30 -18
View File
@@ -149,7 +149,7 @@ you can pass as many variant parameters as you need:
Note that the variant parameters are not made available to the underlying partial template.
They are only use to create a unique cache key.
## Built-in Partials
## Using the Built-in Partials
* Google Analytics
Hugo ships with prebuilt internal templates for Google Analytics tracking, including both synchronous and asynchronous tracking codes.
@@ -180,31 +180,39 @@ Hugo ships with support for [Disqus](https://disqus.com/), a third-party service
Your theme may already support Disqus, but even it if doesn’t, it is easy to add.
# Disqus Support
### Disqus Support
## Adding Disqus to a template
#### Adding Disqus to a template
Hugo comes with all the code you would need to include load Disqus. Simply include the following line where you want your comments to appear:
{{ template "_internal/disqus.html" . }}
## Configuring Disqus
#### Configuring Disqus
That template requires you to set a single value in your site config file, e.g. config.yaml.
That template requires you to set a single value in your site `config`:
disqusShortname = "XYW"
```toml
disqusShortname = "yourdiscussshortname"
```
Additionally, you can optionally set the following in the front matter
for a given piece of content:
Or with a `config.yml`:
* **disqus_identifier**
* **disqus_title**
* **disqus_url**
```yaml
disqusShortname: "yourdiscussshortname"
```
## Conditional Loading of Disqus Comments
You also have the option to set the following in the front matter for a given piece of content:
Users have noticed that enabling Disqus comments when running the Hugo web server on localhost causes the creation of unwanted discussions on the associated Disqus account. In order to prevent this, a slightly tweaked partial template is required. So, rather than using the built-in `"_internal/disqus.html"` template referenced above, create a template in your `partials` folder that looks like this:
* `disqus_identifier`
* `disqus_title`
* `disqus_url`
#### Conditional Loading of Disqus Comments
Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account. In order to prevent this, a slightly tweaked partial template is required. So, rather than using the built-in `"_internal/disqus.html"` template referenced above, create a template in `layouts/partials` that looks like the following:
{{% input "layouts/partials/disqus.html" %}}
```html
<div id="disqus_thread"></div>
<script type="text/javascript">
@@ -224,15 +232,19 @@ Users have noticed that enabling Disqus comments when running the Hugo web serve
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
```
{{% /input %}}
Notice that there is a simple `if` statement that detects when you are running on localhost and skips the initialization of the Disqus comment injection.
The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`.
Now, reference the partial template from your page template:
You can then reference the partial template:
{{ partial "disqus.html" . }}
{{% input "disqus-reference.html" %}}
```golang
{{ partial "disqus.html" . }}
```
{{% /input %}}
# Alternatives
## Alternatives
A few alternatives exist to [Disqus](https://disqus.com/):
doc-concept-roadmap.md
+2 -2
View File
@@ -1,5 +1,5 @@
## Hugo Docs Concept Roadmap
## Roadmap
- [ ] Addition of Algolia search
- [ ] "Documentation" channel on Hugo discourse
- [ ] GH Wiki for more extensive contribution guidelines
- [ ] GH Wiki for more extensive contribution guidelines
eof-error.md
-49
View File
@@ -1,49 +0,0 @@
---
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]
notesforauthors:
---
## `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
questions-for-reviewers.md
-1
View File
@@ -1 +0,0 @@
*
strategy.md
+160
View File
@@ -0,0 +1,160 @@
<!-- MarkdownTOC -->
- [Assumptions][assumptions]
- [Goals][goals]
- [Audience][audience]
- [Persona][persona]
- [End User: Developer][end-user-developer]
- [End User: Themes \(i.e. blogger/author/\)][end-user-themes-ie-bloggerauthor]
- [Requirements][requirements]
- [Technical][technical]
- [SEO][seo]
- [Editorial/Content][editorialcontent]
- [UX][ux]
- [Author Experience \(AX\)][author-experience-ax]
- [Visual Design][visual-design]
<!-- /MarkdownTOC -->
**Updated 2017-02-21**
This is a *very* schlocky version of the documentation I'd put together in my professional life. That said, I think the following pieces are still important and should provide some insight as to how I've approached reworking the Hugo documentation over the last three months.
<a name="assumptions"></a>
## Assumptions
> **Note**: These assumptions are empirical; i.e. the result of me spending a large (and potentially unhealthy) amount of time on the [Hugo Discussion Forum](https://discuss.gohugo.io).
* The current documentation is...
* confusing for new users
* a common complaint in the Hugo forums [example discussion 1][],[example discussion 2][]
* Lacks structure and therefore...
* doesn't scale (as demonstrated by [patch pages](http://gohugo.io/taxonomies/templates/) that seem out of place or require unnecessary drilldown).
* is inconsistent in its terminology, style, and (sometimes) layout
* limits the efficacy of Alogolia's document search feature
* Does not itself leverage Hugo's more powerful feature (e.g., there is only *one* archetype and five shortcodes for what is ultimately a complex documentation site).
* Leveraging these features would help address the aforementioned shortcomings (i.e., scalability, consistency, and search)
* Assumes a higher level of Golang proficiency than is realistic for newcomers to the language or web development in general.
* If you don't make it *very easy* for authors to contribute to documentation correctly, they will inevitably contribute *incorrectly*.
* Content modeling is king
* Go DRY (e.g. with shortcodes)
* Require metadata
<a name="goals"></a>
## Goals
Hugo documentation should...
* reduce confusion surrounding `list` vs `section` vs `page` vs `content type`,etc., and thereby
* make it easier for new users to get up and running
* create better consistency and scalability Hugo-dependent projects (namely, http://themes.gohugo.io)
* reduce frequency of such questions in the Hugo Discuss Forum
* not require any degree of Golang proficiency from end users.
* That said, Hugo *can* act as a bridge for those interested in learning Golang (e.g., by including `godocref` as a default front matter field in [`archetypes/functions.md`](https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md)).
* be easy to expand and edit for contributors Editing and expanding documentation should be easiest for *contributors**, whereas usage of documentation should be easiest for *end users*.
* be equally accessible via mobile, tablet, desktop, *and* offline.
* not include an "extras" section because [this is the last place end users look to learn about Hugo](https://discuss.gohugo.io/t/site-with-different-lists-of-sections/5536/3). Instead all "extras" should be integrated into a new
* easily scaffold for future multilingual versions
<a name="audience"></a>
## Audience
* Primary: Web developers interested in static site generators
* Secondary: Web publishers (bloggers, authors)
* Tertiary: Web developers interested in learning Golang
<a name="persona"></a>
## Persona
<a name="end-user-developer"></a>
### End User: Developer
* Limited proficiency in Git and DVCS
* No to little proficiency in Golang
* working proficiency in front-end development---HTML, CSS, JS---but not necessarily front-end build tools
* familiarity with at least one double-curly templating language (e.g., liquid, Twig, Swig, or Django)
* proficiency in the English language
* proficiency in other languages (for future multilingual versions)
<a name="end-user-themes-ie-bloggerauthor"></a>
### End User: Themes (i.e. blogger/author/)
* Limited proficiency in the command line/prompt
* Proficiency in a supported content format (specifically markdown)
* Access to static hosting but with limited proficiency in basic deployments
<a name="requirements"></a>
## Requirements
<a name="technical"></a>
### Technical
- [X] Built with Hugo
- [X] Performant (e.g., 80+ on [Google Page Speed Score](https://developers.google.com/speed/pagespeed/insights/))
- [X] Front-end build tools for concatenation, minification
- [ ] CDN
<a name="seo"></a>
### SEO
- [X] [Open Graph Protocol](http://ogp.me/)
- [X] [schema.org](http://schema.org)
- [ ] [JSON+LD](https://developers.google.com/schemas/formats/json-ld), [validated](https://search.google.com/structured-data/testing-tool)
- [X] Consistent heading structure
- [X] Semantic HTML5 elements (e.g., `article`, `main`, `aside`, `dl`)
- [ ] SSL
- [ ] AMP
<a name="editorialcontent"></a>
### Editorial/Content
- [X] Basic style guide
- [X] Contribution guidelines (see [working draft on live site](https://hugodocsconcept.netlify.com/contribute-to-hugo/contribute-to-the-hugo-docs/))
- [X] Standardized content types (i.e, [see current archetypes](https://github.com/rdwatters/hugo-docs-concept/tree/master/themes/hugodocs/archetypes)
- [X] New Content Model, including taxonomies ([see tags page]())
- [ ] DRY. New shortcodes for repeat content (e.g., list of aliases, list of page variables)
- [X] New site architecture and content groupings
- [ ] Examples pulling from a single sample website (including in docs source) for consistent code samples or in-page tutorials
#### [Content Strategy Statement](http://contentmarketinginstitute.com/2016/01/content-on-strategy-templates/)
> The Hugo documentation increases the Hugo user base and strengthens the Hugo community by providing intuitive, beginner-friendly content that makes visitors to the site feel excited and confident that Hugo is the ideal choice for all their static web publishing needs.
#### [Editorial Mission](http://contentmarketinginstitute.com/2015/10/statement-content-marketing/)
> The Hugo documentation is a joint effort between the Hugo maintainers and the open-source community. Hugo documentation is designed to promote Hugo, the world's fastest, friendliest, and most extensible static site generator. Hugo documentation is the primary vehicle by which the Hugo team reaches our target audiences. When visitors comes to our site, we want them to install Hugo, developer a new site in Hugo, and share their progress with the community at large.
<a name="ux"></a>
## UX
- [ ] Share buttons
- [ ] Copy-page links
- [X] Copyable code blocks (via highlight.js, extended for hugo-specific keywords)
- [X] Dual in-page navigation
- [X] Smooth scrolling
<a name="author-experience-ax"></a>
## Author Experience (AX)
- [X] Easy scaffolding of content types (CLI)
- [X] Type-based content storage model and scope (archetypes)
<a name="visual-design"></a>
## Visual Design
- [X] Clean typography with open-source font
- [X] Optimal line length (50-80 characters)
- [X] Consistent vertical rhythm
- [X] Responsive
- [X] Flexbox
- [X] Typography (via ems)
- [X] Custom iconography
- [X] Design assets versioned with source ([see design resources directory](https://github.com/rdwatters/hugo-docs-concept/tree/master/dev-and-design-resources))
- [X] [WCAG color contrast requirements](http://webaim.org/blog/wcag-2-0-and-link-colors/)
- [X] [Sass Guidelines for Source Organization](https://sass-guidelin.es/)
- [X] Abstracted color palette
- [X] Abstracted typefaces (multiple open-source fonts available)
[example discussion 1]: https://discuss.gohugo.io/t/frustrated-with-documentation/2810
[example discussion 2]: https://discuss.gohugo.io/t/documentation-restructure-and-design/1891
themes/hugodocs/layouts/_default/baseof.html
+1
View File
@@ -3,6 +3,7 @@
{{- partial "site-head.html" . -}}
<body>
{{- partial "site-header.html" . -}}
{{- partial "site-search.html" . -}}
<div class="all-content-wrapper{{if .IsHome}} home{{end}}" id="all-content-wrapper">
{{ block "main" . }}
{{ end}}
themes/hugodocs/layouts/partials/site-header.html
+3 -8
View File
@@ -5,12 +5,7 @@
<a href="/" id="home-link">
<img src="{{$base}}images/hugo-logo/hugo-logo-wide.png" alt=""><span class="hugo-v">v{{$version}}</span>
</a>
<!-- From https://buttons.github.io/. -->
<a class="github-button" href="https://github.com/spf13/hugo" data-icon="octicon-star" data-style="mega" data-count-href="/spf13/hugo/stargazers" data-count-api="/repos/spf13/hugo#stargazers_count" data-count-aria-label="# stargazers on GitHub" aria-label="Star spf13/hugo on GitHub">Star</a>
</div>
</header>
<a href="#" id="toggle-search">
<i class="icon-search"></i>
</a>
<form id="site-search-form" action="">
<input type="search" id="search-input" placeholder="Search {{.Site.Title}}...">
</form>
</header>
themes/hugodocs/layouts/partials/site-search.html
+6
View File
@@ -0,0 +1,6 @@
<a href="#" id="toggle-search">
<i class="icon-search"></i>
</a>
<form id="site-search-form" action="">
<input type="search" id="search-input" placeholder="Search {{.Site.Title}}...">
</form>