Read the Docs First

Hours went into hacking CSS and layout files to add features that were already supported by the theme. The fix was sitting in the documentation the entire time. Classic.

The detour

• Tweaked templates to adjust the header and footer.
• Overrode list and single layouts to change typography and spacing.
• Added custom CSS for link styles and code blocks.
• Broke pagination twice and then fixed it the wrong way.

Most of this was unnecessary. Smigle already exposed the options. Hugo had the rest covered.

What the docs already solved

• Theme parameters: many toggles live in the theme config. A few lines in config.* would have done it.
• Partials and blocks: Hugo supports safe overrides without forking the theme. Drop a matching file in /layouts/partials/ or /layouts/_default/ and it takes precedence.
  Docs: Hugo templates, partials, list and single templates.
• Shortcodes: no need to hand-roll Markdown HTML. Use or extend shortcodes.
  Docs: Shortcodes.
• Theme specifics: Smigle’s README and example site covered the header, footer, menus, and typography variables. Reading those first would have saved the afternoon.
  Smigle: theme repo

A simple workflow to avoid this next time

1. Scan the theme README and the exampleSite/ to see supported params and patterns.
2. Search the repo for the class or partial you plan to change before editing anything.
3. Prefer overrides in /layouts/ and /assets/ over editing theme files directly.
4. Keep a scratch file that records each change and the reason for it.
5. Only fork the theme if an upstream change is truly needed.

Thanks for reading. If you have a favourite docs-first trick, send it over. It might save someone a few hours of wheel-spinning.