Standardizing doc's proposal


#1

Man, I really love Hugo the more I use it! Unfortunately I come from a Node background and so I’m in the docs a lot. I’d like to take an afternoon to go through and help standardize the documentation, would this be OK for me to do?

I’d like to see the same documentation style used throughout, like for example, when defining properties. I’m not sure what the best practices are in Go, but if we can create a standard in this thread it could help us improve the docs a bit.

Here are some proposals, I’d like to get some feedback before I dive into it (if it’s OK):

  • When documenting code blocks, indent with 2 spaces. This is for readability within the docs (which are only 544px wide). Too much horizontal scrolling makes it hard to follow the code blocks

  • Use ```html. Instead of using indentation based code blocks, use the 3 tick format to apply syntax highlighting.

  • Treat template blocks as code blocks. I don’t know if this is best practice, but do this:

{{ range .Pages }}
   <li> {{ .Title }}
{{ end }}

instead of:

{{ range .Pages }}
<li> {{ .Title }}
{{ end }}
`.Title`
: `String` (Optional) Property description here. **Default:** `Some value`

.Title
: String (Optional) Property description here. Default: Some value


#2

Your work in this area would be greatly appreciated.

I have only one comment to your examples. I think you should get rid of the backticks for the property names:

So

`.Title`
: `String` (Optional) Property description here. **Default:** `Some value`

Becomes:

.Title
: `String` (Optional) Property description here. **Default:** `Some value`

I suspect the example you linked to are written by me, but I have since changed my mind on this …


#3

Awesome sounds good, I’ll probably start them tomorrow!