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 }}
- Use this method for properties: As seen here
`.Title`
: `String` (Optional) Property description here. **Default:** `Some value`
.Title
: String (Optional) Property description here. Default: Some value