First, apologies if I have the wrong tag/category. I don’t see a tag for general questions about how Hugo works. In this case, I’d like to learn what Hugo can do and generally how Hugo does a few things. I can then figure out the rest of what we need.
Currently, we’re using Writerside to document two enterprise level software products with Fortune 500 clients. I’d like to move to a tool like Hugo if its feature set is equal or better than what we have. Could someone take a moment to tell me if Hugo can do several things and, if so, what the feature is called in Hugo so I can look it up in docs? I’ve looked through docs for these features specifically but cannot find answers so far (sorry).
Here’s what we have plus what we’re looking for in a replacement tool:
Publish multiple versions of docs using a single file set that is 90% the same across doc versions. Ideally with a version dropdown list in or near the top navigation links. This could be using conditionals to wrap content for a specific version that’s published only for that version. Or Git branches. Or perhaps another technique.
Reuse content paragraphs across files. For example, a description how to access a tool that’s used in an introduction topic and a how to topic. With Writerside, this is a reference in the Markdown file to another Markdown file.
Variables for common names used throughout the docs. For example, the name of applications and features that might change over time.
Tabs/Dropdown lists to show/hide long content, code, and other information that makes scrolling difficult.
Output content to PDF files using a cover page and custom TOC for the PDF.
Integration with Bitbucket, although we also have Gitlab access.
I assume linting and a local preview capability are available through CLI and other tools.
Appreciate any help understanding what Hugo can do generally and what the features are called in Hugo. Thank you!
Thanks @bep do you have an idea if next version is in weeks, months, or later? It would help us plan what we’re doing, what goes first second and third. Appreciate quick reply!
Thanks @jmooring! That’s so helpful. I can build off these answers to put together what we’d need to do to our Markdown and templates to use Hugo.
And if you guys know roughly when the publishing multiple versions of a document from a single file set will be released, that would help me with planning our overall schedule.
As for Bitbucket, you’re right about Git. It’s abstracted with the Writerside plugin. There’s a commit process that uses Git to work with Bitbucket. It’s Git that’s important, not the destinations like Github, Bitbucket, etc.
jmooring’s answer is on point, as always. I actually learned about the details shortcode myself by reading it.
To expand on this, with modern web browsers’ ability to save PDF’s from their print dialogs, I have found that with a bit of instruction, css that filters the “page” media to what you want to show up on it, and a window.print() js call on an icon or button, most users can figure this out without having to do anything extravagant on the web dev side.