Hugo Content Tips

Mon, 01 Jan 0001 00:00:00 +0000

Docsy is a theme for the Hugo static site generator. If you’re not already familiar with Hugo this page provides some useful tips and potential gotchas for adding and editing content for your site. Feel free to add your own!

Linking

By default, regular relative URLs in links are left unchanged by Hugo (they’re still relative links in your site’s generated HTML), hence some hardcoded relative links like [relative cross-link](../../peer-folder/sub-file.md) might behave unexpectedly compared to how they work on your local file system. You may find it helpful to use some of Hugo’s built-in link shortcodes like relref to avoid broken links in your generated site. For example a {{< ref "filename.md" >}} link in Hugo will actually find and automatically link to your file named filename.md.

Organizing Your Content

Mon, 01 Jan 0001 00:00:00 +0000

If you have a look at our Example Site, you’ll see that we’ve organized the Documentation section into a number of subsections, each with some recommendations about what you might put in that section.

Do I need to use this structure?

Absolutely not! The site structure in the Example Site was created to meet the needs of large docsets for large products with lots of features, potential tasks, and reference elements. For a simpler docset (like this one!), it’s fine to just structure your docs around specific features that your users need to know about. Even for larger documentation sets, you may find that the structure isn’t useful “as is”, or that you don’t need to use all the section types.

Best Practices on OINK

Hugo Content Tips

Linking

Organizing Your Content

Do I need to use this structure?