Hugo-Primer

Hugo-Primer is a Hugo blog theme that restyles the static site generator with GitHub's Primer CSS and adds blog features like TOC, math rendering, and social share buttons.

What is Hugo-Primer?

Hugo-Primer is a Hugo theme built on GitHub's Primer CSS design system, created by developer qqhann. It takes markdown posts with front matter and renders them as a GitHub-style blog with a header menu, sidebar, and content area. The theme is installed by cloning its GitHub repository into a Hugo project's themes directory and runs entirely on Hugo's static generator — no JavaScript build step required.

Key Features

• Primer CSS styling — Uses GitHub's open-source Primer CSS for buttons, navigation, and the overall visual language you recognize from GitHub.
• Menu bar header — A top navigation bar for the site, configured through Hugo's standard menu system.
• Colored code pen — Syntax highlighting via Hugo's built-in Pygments support, enabled by setting pygmentsCodeFences = true and pygmentsUseClasses = true.
• Math rendering — MathJax.js is integrated; enable it site-wide with the math param or per page via front matter.
• Table of contents — An automatically generated TOC appears in the sidebar, toggleable per post with toc: false.
• Tags and categories — List them in front matter and they display in the sidebar, letting readers navigate related posts.
• Social share buttons — Configurable share targets for Twitter, Hatena, Facebook, and Pocket via the shareTo parameter.
• Ruby annotation shortcode — A shortcode to display pronunciation guides on characters, built on HTML ruby elements.

Who is it for?

Developers and technical writers who prefer GitHub's aesthetic for their personal blogs and want a familiar look. Bloggers publishing in Chinese, Japanese, or Korean benefit from the theme's CJK support, which is enabled with hasCJKLanguage = true. Writers who need to display LaTeX math in posts will appreciate the built-in MathJax integration.

What can you do with Hugo-Primer?

• Write a technical blog: Publish markdown posts with tags, categories, and syntax-highlighted code blocks in a GitHub-style layout.
• Share posts to social media: Choose which share buttons appear with shareTo = ["Twitter", "Hatena", "Facebook", "Pocket"].
• Display math formulas: Enable MathJax globally or per post to render LaTeX equations inline and in blocks.
• Add pronunciation guides: Use the ruby shortcode to annotate characters with readings, useful for language-learning content.

How does Hugo-Primer work?

Install it by running git clone https://github.com/qqhann/hugo-primer.git themes/hugo-primer, then start a local server with hugo server --theme=hugo-primer. You can copy the exampleSite/ directory into your project to get a working configuration quickly. Configuration lives in config.toml, where you set params like hasCJKLanguage, pygmentsCodeFences, and shareTo.

FAQ

Is Hugo-Primer free?

Yes. The theme is open source under the MIT license, so you can use, modify, and distribute it freely.

Can I use Hugo-Primer with a language other than English?

Yes, the theme supports CJK languages. Setting hasCJKLanguage = true is recommended for Chinese, Japanese, or Korean content, and the example site includes a Japanese article.

Does Hugo-Primer support comments?

Yes. Disqus comments are enabled by default on posts; set comments: false in front matter to hide them on individual pages.

How do I change the date display on a post?

Set showdate: false in the post's front matter to hide the date. The default is true.

Can I enable math only on certain posts?

Yes. Set math = false site-wide in config.toml and then add math: true to the front matter of individual posts to enable MathJax for those pages only.