https://github.com/irkode/highlightjs-hugo
HighlightJS-Hugo - Syntax highlighting for Hugo templates
https://github.com/irkode/highlightjs-hugo
Last synced: about 1 month ago
JSON representation
HighlightJS-Hugo - Syntax highlighting for Hugo templates
- Host: GitHub
- URL: https://github.com/irkode/highlightjs-hugo
- Owner: irkode
- License: mit
- Created: 2025-09-18T17:36:53.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-28T11:35:58.000Z (8 months ago)
- Last Synced: 2025-09-28T13:25:35.873Z (8 months ago)
- Language: JavaScript
- Size: 39.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Advanced syntax highlighting for HuGo templates
Did you ever wonder why hugo templates seem to be randomly highlighted in [Discourse][]. The answer
is dead simple: _Discourse_ uses [Highlight.js][] for syntax highlighting which does not support Go
and Hugo templates.
It could look so nice
To improve that we implemented
- _Highlight.js_ grammars
- _Discourse_ theme components.
Both supporting the full set of Hugo's template keywords, built-in functions and aliases.
Read more details in our [Documentation][] or directly pick them from our [Releases][] page.
## Provided plugins
Currently we provide the following components
* Highlight.js
Two grammars for [Hugo][]'s _Text_ and _HTML_ templates with auto detection[^2] and full keyword support.
Additionally we provide a ready to use _browser build_ with only our grammars[^2].
* Discourse
Two theme components utilizing the above _Text_ and _HTML_ grammars.
## Download
Ready to use modules are available as artifacts on our [Releases][] Page.
## Usage and documentation
Follow the instructions included in each artifact's `README.md`. To read before downloading, check
out our [Documentation][]
## Build
For standard use cases see _Download_ above.
### Custom Highlight.js build
To build your own customized _Highlight.js_ installation grab the _highlightjs-hugo_ artifact and
place it in the extra folder of your _Highlight.js_ clone. Build that just as any other
_Highlight.js_ grammar or a customized build.
With a customized build, we add the _Hugo_ keyword tables to the _Highlight.js_ core so these will
get packed only once. The result is an unpacked saving of 10KB for the final engine.
### Build our sources
We build our stuff using custom scripts; a combination of powershell, node and _Hugo_. These scripts
work fine for us. May work for you but no guarantee. Listed Version numbers are the on we use, might
work with others.
We are on Windows 11 Professional. Could be working for unix like systems, but that is untested.
Have a look at our CI workflow script for the bare commands on a GitHub Ubuntu runner.
- Components that have to be there
- Hugo - 0.160.1+
- Go 1.26.1+
- Node 22.14.0 (highlight.js requirement)
- Components automatically provided by the build scripts
- _Highlight.js_ 11.11.1
- hugoDocs (as a hugo module)
- Build all
```powershell
git clone https://github.com/irkode/highlightjs-hugo/ highlightjs-hugo
set-location highlightjs-hugo
.\build.ps1 -Verbose
```
- grab the results from `release` folder
The Powershell script provides a `Get-Help`.
Be aware that that is in no way a general purpose build script. It just provides shorthands for our
local development process. For special _Highlight.js_ build configurations you will need to directly
use the standard _Node_ and _npm_ scripts.
## Contributing and Issues
Never say never, but currently it's our working playground, nothing where one could do stable
contributions right now.
Use the [Issue tracker][] for reporting bugs, asking question or raise ideas.
## Hugo as a generator
Hugo is a powerful templating engine, and we utilize it to generate and assemble our grammars and
discourse plugins.
- fetch function and aliases from hugoDocs
- generate keyword tables for the plugins
- generate the hugo-lib module (grammar and keyword Javascript module)
- generate Javascript code and supplementary files
- create READMEs
- generate tests
- create source structure for our release assets
- generate Discourse plugins based on the build results
- and ofc for the standard use case - the documentation pages
Take it as a nifty showcase to use Hugo as a generic templating and publishing engine -- beyond web
sites.
If you want to dig in, you can find that here
[](https://github.com/irkode/highlightjs-hugo/tree/main/build/hugen)
## License
This package is released under the MIT License. See [LICENSE](LICENSE) file for details.
## Author & Maintainer
- Irkode
## Links
- [highlightjs-hugo][] : The main repository with additional grammars and plugins. Have a look
- [Documentation][] : All about Highlight 4 Hugo
- [Highlight.js][] : The Internet's favorite JavaScript syntax highlighter supporting Node.js and
the web
- [Hugo][] : The world’s fastest framework for building websites
- [Go HTML template](https://pkg.go.dev/html/template) : Go's html template package
- [Go TEXT template](https://pkg.go.dev/text/template) : Go's text template package
[highlightjs-hugo]: https://github.com/irkode/highlightjs-hugo/
[Documentation]: https://irkode.github.io/highlightjs-hugo/
[Issue tracker]: https://github.com/irkode/highlightjs-hugo/issues
[Highlight.js]: https://highlightjs.org/
[Hugo]: https://gohugo.io/
[Discourse]: https://discourse.gohugo.io/
[Releases]: https://github.com/irkode/highlightjs-hugo/releases/latest
[^1]: and _XML_ cause that's needed for _Hugo-Html_
[^2]: Check out details here: [A word on auto detection](https://irkode.github.io/highlightjs-hugo/highlightjs/hugo-html#a-word-on-auto-detection)