Add tree.md to root

This commit is contained in:
Ryan Watters
2017-02-22 12:01:00 -06:00
parent 27f206de42
commit 48fecc4265
6 changed files with 354 additions and 29 deletions
+1 -1
View File
@@ -64,7 +64,7 @@ Hugo ships with a set of predefined shortcodes that represent very common usage.
### `figure`
`figure` is an extension of the image syntax in Markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figurelement].
`figure` is an extension of the image syntax in Markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
The `figure` shortcode can use the following named parameters:
@@ -19,26 +19,48 @@ Documentation is an integral part of any open source project. The Hugo docs were
## Edit Locally and Submit a Pull Request
**IN DEVELOPMENT**
## How Content is Ordered in the Hugo Docs
**IN DEVELOPMENT**
## Creating New Files from Archetypes
**IN DEVELOPMENT**
### New Default Content
**IN DEVELOPMENT**
### New Function
**IN DEVELOPMENT**
### New Showcase
**IN DEVELOPMENT**
### New Tutorial
## Code Block Shortcodes
**IN DEVELOPMENT**
## Code Block Shortcode Examples
**IN DEVELOPMENT**
### Input Code Block
**IN DEVELOPMENT**
### Output Code Block
**IN DEVELOPMENT**
### Example Site Code Block
**IN DEVELOPMENT**
## Blockquotes
@@ -49,6 +71,9 @@ Documentation is an integral part of any open source project. The Hugo docs were
> Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - [SourceForge][sourceforge]
Both `note` and `warning` with a single, *optional* argument for the admonition title. If the title, a [positional parameter][shortcodeparams]
{{% note "Admonitions are **NOT** Blockquotes" %}}
Previous versions of the Hugo documentation used [Markdown `<blockquote>` syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes) to draw attention to content. This is not the [intended semantic use of the `<blockquote>` element](http://html5doctor.com/cite-and-blockquote-reloaded/).
{{% /note %}}
@@ -101,10 +126,15 @@ This is a warning, which should be reserved for *important* information like bre
## Editorial Style Guide
The Hugo docs are not especially prescriptive in terms of grammar and usage. We encourage everyone to contribute, regardless of your writing style. **It's more important to contribute *some* documentation than no documentation at all**. That said, here are a few pointers to help the project maintain more consistency:
{{% note %}}
It's more important to contribute *some* documentation than no documentation at all. We need your help!
{{% /note %}}
The Hugo docs are not especially prescriptive in terms of grammar and usage. We encourage everyone to contribute, regardless of your writing style. That said, here are a few pointers to help the project maintain more consistency:
## How Content is Ordered in the Docs
**IN DEVELOPMENT**
## Be Mindful of Aliases
@@ -112,4 +142,5 @@ Use aliases sparingly. The following table shows a list of all the aliases used
{{< allaliases >}}
[shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
[sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
+8 -7
View File
@@ -1,13 +1,13 @@
---
title: Local File Templates
linktitle: Local File Templates
description:
description: Hugo's `readerDir` and `readFile` functions make it easy to traverse your project's directory structure and write file contents to your templates.
godocref: https://golang.org/pkg/os/#FileInfo
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [templates]
tags: [files]
tags: [files,directories]
weight: 110
draft: false
aliases: [/extras/localfiles/,/templates/files/]
@@ -23,10 +23,10 @@ With Hugo's [`readDir` function][], you can traverse your website's files on you
The `readDir` function returns an array of [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo). It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e. as found on your server's file system).
Whether the path is absolute or relative makes no difference, because&mdash;at least for `readDir`&mdash;the root of your website (typically `./public/`) in effect becomes both:
Whether the path is absolute or relative does not matter because---at least for `readDir`---the root of your website (typically `./public/`) in effect becomes both:
1. The filesystem root; and
1. The current working directory.
1. The file system root
2. The current working directory
## Example Shortcode: List Directory's Files
@@ -40,7 +40,7 @@ This shortcode [has already been included in this very website][]. So, let's lis
{{< directoryindex path="/static/css" pathURL="/css" >}}
This is the call that rendered the above output:
The following is the [shortcode declaration][shortcodes] used to render the above output:
```html
{{</* directoryindex path="/static/css" pathURL="/css" */>}}
@@ -51,4 +51,5 @@ The initial slash `/` in `pathURL` is important. Otherwise, `pathURL` becomes re
{{% /note %}}
[has already been included in this very website]: https://github.com/spf13/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html
[`readDir` function]: /functions/readdir/
[`readDir` function]: /functions/readdir/
[shortcodes]: /content-management/shortcodes/
+1 -1
View File
@@ -7,7 +7,7 @@
{{- range $files }}
<tr>
<td>{{ .Size }}</td>
<td><a href="{{ $pathURL }}{{ .Name | relURL }}"> {{ .Name }}</a></td>
<td><a href="{{ $pathURL }}{{ .Name | relURL }}" target="_blank"> {{ .Name }}</a></td>
</tr>
{{- end }}
</table>
+24 -18
View File
@@ -1,6 +1,6 @@
# Hugo Docs Strategy, Tactics, and Requirements
# Hugo Docs Concept Strategy, Tactics, and Requirements
> **Note:** Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *very schlocky* version of the documentation required for a real content strategy.
> **Disclaimer:** Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *very schlocky* version of the documentation required for a real content strategy.
**Updated 2017-02-21**
@@ -21,7 +21,7 @@
## 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). Google analytics *may* provide more quantitative insight into actual Hugo docs usage. I should also mention that these are *assumptions* and not *criticisms*. I **LOVE** Hugo.
> **Note**: These assumptions are *empirical*. In other words, they are the result of me spending a large (and potentially unhealthy) amount of time on the [Hugo Discussion Forum](https://discuss.gohugo.io). Google analytics *may* provide more quantitative insight into actual Hugo docs usage. These are *assumptions* and not *criticisms*. I **LOVE** Hugo.
* The current documentation is
* confusing for new users
@@ -37,6 +37,7 @@
* content modeling is king
* go DRY (e.g., with shortcodes)
* set required metadata
* develop for contribution guidelines to dev *and* docs
## Goals
@@ -61,20 +62,24 @@ Hugo documentation should...
## Persona
### End User: Developer
### End User: SSG Developer
* Limited proficiency in Git and DVCS
* No to little proficiency in Golang
The SSG developer has
* 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)
### End User: Themes (i.e. blogger/author/)
### End User: Themes (i.e. blogger/author/hobbyist)
* 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
The themes end user has
* limited proficiency in the command line/prompt
* proficiency in a supported content format (specifically markdown)
* access to static hosting but with limited proficiency in deploying a static website
## Requirements
@@ -84,8 +89,8 @@ Hugo documentation should...
- [X] Performant (e.g., 80+ [Google Page Speed Score](https://developers.google.com/speed/pagespeed/insights/?url=https%3A%2F%2Fhugodocsconcept.netlify.com%2Fabout-hugo))
- [X] Front-end build tools for concatenation, minification
- [X] Browser compatibility: modern (i.e. Chrome, Edge, Firefox, Safari) and IE11
- [ ] AMP?
- [ ] CDN
- [ ] AMP?
### SEO
@@ -99,7 +104,8 @@ Hugo documentation should...
### Editorial/Content
- [X] Basic style guide
- [ ] Basic style guide
- The style guide should server to facilitate a more consistent UX for the site but not deter contributors to the documentation
- [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][tagspage])
@@ -109,19 +115,19 @@ Hugo documentation should...
#### [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.
> The Hugo documentation increases the Hugo user base and strengthens the Hugo community by providing intuitive, beginner-friendly usage guides. Hugo documentation makes visitors feel excited and confident that Hugo is the ideal choice for all their static website development 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.
> 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 its target audiences. When visitors comes to the Hugo documentation, we want them to install Hugo, develop a new static website with our tool, and share their progress and insights with the Hugo community at large.
## UX/UI
- [X] Copyable code blocks (via highlight.js, extended for hugo-specific keywords)
- [X] Dual in-page navigation (i.e. for site nav and in-page TOC)
- [X] Dual in-page navigation (i.e. site nav *and* in-page TOC)
- [X] Smooth scrolling
- [X] [RTD-style admonitions][admonitions] (see [example admonition shortcode](https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/note.html) and [examples on published site](http://localhost:1313/contribute-to-hugo/contribute-to-the-hugo-docs/#admonition-short-codes))
- [ ] Share buttons: Reddit, Twitter, LinkedIn, and "Copy Page Url" (the last of which has strongest utility for referencing in forums)
- [ ] Share buttons: Reddit, Twitter, LinkedIn, and "Copy Page Url"; the last of these provides the strongest utility for docs references in the Hugo forums
## Author Experience (AX)
@@ -131,8 +137,8 @@ Hugo documentation should...
## Analytics/Metrics
- [X] Google Analytics
- [ ] Content groupings in GA to measure usage and define content gaps
- [ ] Automated reports
- [ ] Content groupings (GA) to measure usage, behavior flow, and define content gaps
- [ ] Automated reports (GA)
> **Note:** These are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc.
+287
View File
@@ -0,0 +1,287 @@
**Content Files at a Glance**
```
.
├── _index.md
├── about-hugo
│   ├── _index.md
│   ├── benefits-of-static.md
│   ├── hugo-features.md
│   ├── license.md
│   ├── roadmap.md
│   ├── what-is-hugo.md
│   └── why-i-built-hugo.md
├── commands
│   └── _index.md
├── content-management
│   ├── _index.md
│   ├── archetypes.md
│   ├── comments.md
│   ├── content-organization.md
│   ├── content-summaries.md
│   ├── content-types.md
│   ├── cross-references.md
│   ├── front-matter.md
│   ├── menus.md
│   ├── multilingual-mode.md
│   ├── sections.md
│   ├── shortcodes.md
│   ├── supported-content-formats.md
│   ├── table-of-contents.md
│   ├── taxonomies.md
│   └── url-management.md
├── contribute-to-hugo
│   ├── _index.md
│   ├── add-your-site-to-the-showcase.md
│   ├── contribute-to-hugo-development.md
│   └── contribute-to-the-hugo-docs.md
├── developer-tools
│   ├── _index.md
│   ├── migrate-to-hugo.md
│   └── syntax-highlighting.md
├── functions
│   ├── _index.md
│   ├── abslangurl.md
│   ├── absurl.md
│   ├── after.md
│   ├── apply.md
│   ├── base64decode.md
│   ├── base64encode.md
│   ├── chomp.md
│   ├── countrunes.md
│   ├── countwords.md
│   ├── dateformat.md
│   ├── default-function.md
│   ├── delimit.md
│   ├── dict.md
│   ├── echoparam.md
│   ├── emojify.md
│   ├── findre.md
│   ├── first.md
│   ├── get.md
│   ├── getenv.md
│   ├── getpage.md
│   ├── haschildren.md
│   ├── hasmenucurrent.md
│   ├── hasprefix.md
│   ├── highlight.md
│   ├── htmlescape.md
│   ├── htmlunescape.md
│   ├── humanize.md
│   ├── i18n.md
│   ├── imageconfig.md
│   ├── in.md
│   ├── index-function.md
│   ├── int.md
│   ├── intersect.md
│   ├── ismenucurrent.md
│   ├── isset.md
│   ├── jsonify.md
│   ├── last.md
│   ├── lower.md
│   ├── markdownify.md
│   ├── math.md
│   ├── md5.md
│   ├── param.md
│   ├── partialcached.md
│   ├── plainify.md
│   ├── pluralize.md
│   ├── printf.md
│   ├── querify.md
│   ├── range.md
│   ├── readdir.md
│   ├── readfile.md
│   ├── rel.md
│   ├── rellangurl.md
│   ├── relref.md
│   ├── relurl.md
│   ├── render.md
│   ├── replace.md
│   ├── safecss.md
│   ├── safehtml.md
│   ├── safehtmlattr.md
│   ├── safejs.md
│   ├── safeurl.md
│   ├── scratch.md
│   ├── seq.md
│   ├── sha1.md
│   ├── sha256.md
│   ├── shuffle.md
│   ├── singularize.md
│   ├── slice.md
│   ├── slicestr.md
│   ├── sort.md
│   ├── split.md
│   ├── string.md
│   ├── substr.md
│   ├── the-dot.md
│   ├── time.md
│   ├── title.md
│   ├── trim.md
│   ├── unix.md
│   ├── upper.md
│   ├── urlize.md
│   ├── where.md
│   └── with.md
├── getting-started
│   ├── _index.md
│   ├── basic-usage.md
│   ├── configuration.md
│   ├── directory-structure.md
│   ├── install-hugo.md
│   ├── quick-start.md
│   └── using-the-hugo-docs.md
├── hosting-and-deployment
│   ├── _index.md
│   ├── deployment-with-rsync.md
│   ├── deployment-with-wercker.md
│   ├── hosting-on-bitbucket.md
│   ├── hosting-on-github.md
│   └── hosting-on-gitlab.md
├── mailing-list.md
├── news
│   ├── _index.md
│   ├── press-and-articles.md
│   └── release-notes.md
├── showcase
│   ├── 2626info.md
│   ├── _index.md
│   ├── antzucaro.md
│   ├── appernetic.md
│   ├── arresteddevops.md
│   ├── asc.md
│   ├── astrochili.md
│   ├── aydoscom.md
│   ├── barricade.md
│   ├── bepsays.md
│   ├── bugtrackers.io.md
│   ├── camunda-blog.md
│   ├── camunda-docs.md
│   ├── cdnoverview.md
│   ├── chinese-grammar.md
│   ├── chingli.md
│   ├── chipsncookies.md
│   ├── christianmendoza.md
│   ├── cinegyopen.md
│   ├── clearhaus.md
│   ├── cloudshark.md
│   ├── coding-journal.md
│   ├── consequently.md
│   ├── ctlcompiled.md
│   ├── danmux.md
│   ├── datapipelinearchitect.md
│   ├── davidepetilli.md
│   ├── davidrallen.md
│   ├── davidyates.md
│   ├── devmonk.md
│   ├── dmitriid.com.md
│   ├── emilyhorsman.com.md
│   ├── esolia-com.md
│   ├── esolia-pro.md
│   ├── eurie.md
│   ├── fale.md
│   ├── fixatom.md
│   ├── fxsitecompat.md
│   ├── gntech.md
│   ├── gogb.md
│   ├── goin5minutes.md
│   ├── h10n.me.md
│   ├── hugo.md
│   ├── jamescampbell.md
│   ├── jorgennilsson.md
│   ├── kieranhealy.md
│   ├── klingt-net.md
│   ├── launchcode5.md
│   ├── leepenney.md
│   ├── leowkahman.md
│   ├── lk4d4.darth.io.md
│   ├── losslesslife.md
│   ├── mariosanchez.md
│   ├── mayan-edms.md
│   ├── michaelwhatcott.md
│   ├── mongodb-eng-journal.md
│   ├── mtbhomer.md
│   ├── nickoneill.md
│   ├── ninjaducks.in.md
│   ├── ninya.io.md
│   ├── nodesk.md
│   ├── novelist-xyz.md
│   ├── npf.md
│   ├── peteraba.md
│   ├── promotive.md
│   ├── rahulrai.md
│   ├── rakutentech.md
│   ├── rdegges.md
│   ├── readtext.md
│   ├── richardsumilang.md
│   ├── rick-cogley-info.md
│   ├── ridingbytes.md
│   ├── robertbasic.md
│   ├── scottcwilson.md
│   ├── shapeshed.md
│   ├── shelan.md
│   ├── silvergeko.md
│   ├── softinio.md
│   ├── spf13.md
│   ├── steambap.md
│   ├── stefano.chiodino.md
│   ├── stou.md
│   ├── szymonkatra.md
│   ├── techmadeplain.md
│   ├── tendermint.md
│   ├── thecodeking.md
│   ├── thehome.md
│   ├── tutorialonfly.md
│   ├── ucsb.md
│   ├── upbeat.md
│   ├── vamp.md
│   ├── viglug.org.md
│   ├── vurt.co.md
│   ├── yslow-rules.md
│   ├── ysqi.md
│   └── yulinling.net.md
├── templates
│   ├── _index.md
│   ├── additional-templating-languages.md
│   ├── base-templates-and-blocks.md
│   ├── content-view-templates.md
│   ├── custom-404-page.md
│   ├── data-templates.md
│   ├── go-template-primer.md
│   ├── homepage-template.md
│   ├── local-file-templates.md
│   ├── menu-templates.md
│   ├── pagination.md
│   ├── partial-templates.md
│   ├── rss-templates.md
│   ├── section-and-list-templates.md
│   ├── shortcode-templates.md
│   ├── single-page-templates.md
│   ├── sitemap-template.md
│   ├── taxonomy-templates.md
│   └── template-debugging.md
├── themes
│   ├── _index.md
│   ├── creating-a-theme.md
│   ├── customizing-a-theme.md
│   ├── installing-and-using-themes.md
│   └── theme-showcase.md
├── troubleshooting
│   ├── _index.md
│   ├── accented-characters-in-urls.md
│   └── eof-error.md
├── tutorials
│   ├── _index.md
│   ├── creating-a-multilingual-site.md
│   ├── creating-a-new-theme.md
│   └── migrate-from-jekyll-to-hugo.md
└── variables-and-params
├── _index.md
├── file-variables.md
├── page-variables.md
├── shortcode-git-and-hugo-variables.md
├── site-variables.md
└── taxonomy-variables.md
15 directories, 265 files
```