MiloDocs: Hugo Theme for Tech Writers & Docs Engineers

New theme/module
1

Hi everyone,

I’m putting together an open source theme designed for technical writers and documentation engineers. It’s called MiloDocs (repo), powered by TailwindCSS & VanillaJS.

This theme will eventually contain all of the knowledge I’ve accumulated while using Hugo for docs use cases. This will include some walkthroughs on how to set up multi-version docs and a more in-depth guide to setting up chatGPT on your docs.

MiloDocs is still very much a WIP, but I’d love to hear what you think so far and if you have any layout requests. I’ll be updating this thread over time as I continue to add things.

(This is also my first real open source project, so advice in general is welcome).

Features

Shortcodes

  • include: inline code samples from source files with start/stop options.
  • pdoc: link targeting for embedded pdoc python ref docs.
  • tabs: tabbed content ui
  • prod: handler for product names from site config
  • version: handler for collection-scoped or globally-scoped release versions
  • notice: admonitions of various types
    … More to come!

Content Layouts

  • Glossary: stacked list UI with a-z anchors for quick browsing
  • Tutorials: Coming Soon.
4 Likes
2
  1. Test and correct accessibility issues with a tool like Wave or its extension or Axe. Test in both light and dark modes.
  2. Address performance issues.
  3. I saw you have inline JS in several places. This might be blocked by some web hosts if their Content Security Policy is strict.
  4. In tiles.html, $order variable is undefined.
  5. In js.html, you can call the Algolia script with Hugo’s getRemote.
  6. In head.html, replace <meta name="generator" content="Hugo v0.119.0"> with {{ if .IsHome }}{{ hugo.Generator }}{{ end }}.
  7. markdownify is on the suggested lists of deprecations. Try .Page.RenderString instead RenderString | Hugo
  8. You have a lot of fonts. I’d recommend a maximum of two font faces: one for headings and another for body text.
  9. Convert the content folder into an exampleSite instead.
1 Like
3

Look nice.

1 Like
4

Appreciate these – especially the markdownify callout. I went ahead and replaced markdownify, removed the unused tiles var, and updated the generator tag. I’ll get to the next few soon this week.

I haven’t quite been able to figure out why my JS for the chat functionality can’t be accessed when I try to move it to /assets/js — every other JS i’ve done works fine when I move it. When someone submits a question, it says “submitQuestion()” can’t be found. I’m sure I’ll figure it out eventually, but for now I’ve left it there inside the partial.

5

I am not knowledgeable enough to comment on that, but the last time I tried a similar thing due to CSP violation of onClick, I replaced it with an ID and had some help from Stack Overflow to rewite the JS code to use ID instead of onClick. Perhaps the same can be replicated for other click events.

1 Like