Single page documentation

support
1

Hi there,

Hugo newbie here. Thank you for this very cool project!

I recently started using Hugo to build my app’s public site and I quite like it so far.

I’m now trying to build a documentation page that behaves like this one: https://stripe.com/docs/api
It’s a single giant page but I would like to manage it with a separate markdown file for each section, rather than a giant markdown file.

  1. Is it possible to create a page like that? It must inline multiple pages one after the other, based on a specific order. I suppose the best way would be to have a simple configuration file that list of the individual pages to be included.
  2. Ideally, as the user scrolls down, it must update the url (I believe this uses history.replaceState) and highlight the corresponding page in the side nav.
  3. This should be well integrated with the sitemap. The user should be able to open a link that takes them to a specific page (auto scroll)

That might be a bit much to ask for a static site but I thought I’d ask.

Clement

2

I wonder if this theme gets you part of the way there (some inspiration)? I think it does 1 on your list…and 2 would be solved with some JavaScript.

3

I already have a theme so I would like to get the piece of code that allows to build such a page, so I can use it directly in my theme. That looks promising thanks, I need to experiment with the code from that theme

4

Did you have a look at non-Hugo solutions?

For example: https://www.mkdocs.org/

1 Like
5

Agreed with @funkydan2

When looking at the theme he linked, in short the “single page” documentation is done by:

  • From the homepage template, range through all sections by weight
  • If there are subsections then recursively range through them by weight, if not then range through pages by weight
6

I work on API documentation using Hugo, OAS3, and ReDoc.

The legendary Stripe API page was built by Stripe engineers using lots of CSS, JavaScript, and sweat. Given OAS3 specs, ReDoc can generate something close as a single page app either server-based or bundled.

Trying to replicate the Stripe three-column site in Hugo may not the best use of your time.

Much depends on the type of API you’re trying to document, as well as how much you’re committed to putting everything in Hugo. For example, I generate my reference documents from ReDoc, then I copy them to my Hugo site and refer to them as static files.

7

I’ve got a microblog site, and on the index page, I just range over the posts and show all content for each with {{ .Content }}. That way, I have a separate markdown file for each post, but they all appear on the top page (albeit in a paginator).

https://git.sr.ht/~rickcogley/logr.cogley.info/tree/master/layouts/index.html#L28

I can’t speak to 2, but that should be possible with javascript I would assume. As for the sitemap, each markdown file gets its own entry as expected.

8

Thank you all for your inputs.
You’ve given me quite a few options and food for thought. I will need to investigate further but that does sound promising.
In my case, the documentation is NOT technical, but I do find that single page style of documentation very user friendly because one can glance through the entire content easily without clicking and also search easily. It’s not clear to me how this get indexed by search engines, but it is interesting to see that Google is indexing a separate page for each ‘section’ even though it is really a single giant page.