You can find a blank Godocument template at https://github.com/phillip-england/godocument.
All the commands in this guide assume you are using a Unix-based terminal.
To get started, create a directory and clone the repo within it:
mkdir <your-app-name>
3 | cd <your-app-name>
4 | git clone https://github.com/phillip-england/godocument .
5 | Important
10 | 11 |{text}
12 | 13 | `)}}class g{constructor(e){e.registerComponent("md-warning",` 14 |Warning
24 | 25 |{text}
26 |Correct
36 | 37 |{text}
38 |Godocument is a static site generator inspired by Docusaurus and powered by Htmx. Documenting your code should be simple.
Godocument requires Go version 1.22.0 or greater
A Godocument website can be created using the following steps:
mkdir <your-apps-name>
3 | cd <your-apps-name>
4 | git clone https://github.com/phillip-england/godocument .
5 | go run main.go --reset
6 | godocument.config.json:{
7 | "docs": {
8 | "Introduction": "/introduction.md",
9 | "First Page": "/first-page.md",
10 | "First Section": {
11 | "Second Page": "/first-section/second-page.md"
12 | }
13 | },
14 | "meta": {
15 | "title": "My Website"
16 | }
17 | }
18 | /docs, create first-page.mdtouch /docs/first-page.md
19 | /docs/first-page.md<meta name="description" content="Explore my first page with Godocument"></meta>
20 |
21 | # First Page
22 |
23 | ## Hello, World
24 |
25 | This is the first page I've created using Godocument!
26 | /docs create a directory called /first-sectionmkdir /docs/first-section
27 | /docs/first-section, create a file called second-page.mdtouch /docs/first-section/second-page.md
28 | /docs/first-section/second-page.md<meta name="description" content="Explore my second page with Godocument"></meta>
29 |
30 | # Second Page
31 |
32 | ## Hello, World
33 |
34 | This is the second page I've created using Godocument!
35 | localhost:8080:go run main.go
36 | go run main.go --build
37 | -- To build for production, run:
go run main.go --build <your-server-url>
38 | That's it! Your example is deployment-ready and can be found at /out. You can easily deploy on Github Pages, Amazon S3, or a CDN of your choice.
All Javascript for Godocument is located in /static/js/index.js.
To create a new custom component, first create a class to represent the component.
Let's call this component, simple-component. The constructor should take in a parameter called customComponent, which will be an object built from the CustomComponent class.
The CustomComponent class is already included in Godocument.
class SimpleComponent {
3 | constructor(customComponent) {
4 |
5 | }
6 | }
7 | In onLoad(), be sure to instantiate both CustomComponent and SimpleComponent:
function onLoad() {
8 | // ...
9 |
10 | // defining custom components
11 | let customComponents = new CustomComponent()
12 | new SimpleComponent(customComponents)
13 | }
14 | In the constructor of SimpleComponent call customComponent.registerComponent(className, htmlContent) as follows:
class SimpleComponent {
15 | constructor(customComponent) {
16 | customComponent.registerComponent("simple-component", `
17 | <div>
18 | <h1>Hello, World</h1>
19 | <p>{text}</p>
20 | </div>
21 | `)
22 | }
23 | }
24 | Take note of this line:
<p>{text}</p>
25 | Register component will replace {text} with the innerHTML of the component.
To utilize simple-component, place the following markup in any of your .md files:
<span class='simple-component'>I am a simple component!</span>
26 | Godocument comes with a few components already built. Here they are:
I am created by using this markup in a .md file: <span class='md-important'>I am important!</span>
I am created by using this markup in a .md file: <span class='md-warning'>I am a warning!</span>
I am created by using this markup in a .md file: <span class='md-correct'>That is correct!</span>
Since we are using Goldmark to convert .md files into workable HTML, we have to use the html.WithUnsafe() renderer option when instantiating Goldmark in our project. This will allow us to place HTML elements directly in our .md files.
This is only considered unsafe if the content within our .md files is controlled by our users. In our case, since we will be the ones writing the markup directly, it is not considered unsafe.
Removing html.WithUnsafe() from Goldmark's rendering options will cause Goldmark to ignore any HTML markup within our .md files.
Godocument uses Htmx to provide a single page application user experience. Htmx enables us to do this without the complexity of a Javascript framework.
This functionality is enabled by a single attribute on our <body> tag, hx-boost.
<body hx-boost='true' ...>
3 | Basically, when you click on a navigational link within your website, Htmx will take over and the following will happen:
href of the clicked <a>.<body> from the response will be isolated.<body> will be replaced with the newly received <body>.All of this will be done without a full-page refresh. Since we are generating static pages, the wait time between when a request is clicked and when the response is receieved will be minimal, giving the illusion of a single page experience to the user.
Using Htmx's hx-boost attribute has implications on how we need to think about using Javascript in our application.
Since the <body> is the only thing changed when using hx-boost, the Javascript located in the <head> of our document will only be loaded once. However, Javascript located in the <body> will be ran on each request.
This can create issues when declaring functions, declaring variables, and mounting event listeners.
Godocument makes use of an attribute, loaded, on the <html> tag to avoid reinstantiating variables multiple times.
<html lang="en" loaded="false" ..>
4 | After the page is loaded on the initial visit, this attribute is set to true. This will prevent our variables and functions from being instantiated more than once.
Failing to set loaded="true" on <html> will result in unexpected behavior
Godocument makes use of the function onLoad() to run the appropriate Javascript on all page loads.
function onLoad() {
5 |
6 | // elements
7 | const body = qs(document, 'body')
8 | const sitenav = qs(document, '#sitenav')
9 | const sitenavItems = qsa(sitenav, '.item')
10 | const sitenavDropdowns = qsa(sitenav, '.dropdown')
11 | const pagenav = qs(document, '#pagenav')
12 | const pagenavLinks = qsa(pagenav, 'a')
13 | const article = qs(document, '#article')
14 | const articleTitles = qsa(article, 'h2, h3, h4, h5, h6')
15 | const header = qs(document, '#header')
16 | const headerBars = qs(header, '#bars')
17 | const overlay = qs(document, '#overlay')
18 | const sunIcons = qsa(document, '.sun')
19 | const moonIcons = qsa(document, '.moon')
20 | const htmlDocument = qs(document, 'html')
21 |
22 | // hooking events and running initializations
23 | window.scrollTo(0, 0, { behavior: 'auto' })
24 | new SiteNav(sitenav, sitenavItems, sitenavDropdowns, header, overlay)
25 | new PageNav(pagenav, pagenavLinks, articleTitles)
26 | new Header(headerBars, overlay, sitenav)
27 | new Theme(sunIcons, moonIcons, htmlDocument)
28 |
29 | // web components
30 | doOnce(() => {
31 | customElements.define('md-important', MdImportant)
32 | customElements.define('md-warning', MdWarning)
33 | customElements.define('md-correct', MdCorrect)
34 | })
35 |
36 | // init
37 | Prism.highlightAll();
38 |
39 | // reveal body
40 | zez.applyState(body, 'loaded')
41 |
42 | }
43 | onLoad() is mounted to the window and <body> using the DOMContentLoaded and htmx:afterOnLoad events. Click here to read more about Htmx events.
eReset(window, 'DOMContentLoaded', onLoad) // initial page load
44 | eReset(document.getElementsByTagName('body')[0], "htmx:afterOnLoad", onLoad) // after htmx swaps
45 | DOMContentLoaded will handle the initial page load, while hmtx:afterOnLoad will handle all other navigations.
Since the page is never refreshed using Htmx, we need to make sure we are unmounting events and remounting them on every navigation. eReset() is a handy function that does just that.
function eReset(node, eventType, callback) {
46 | node.removeEventListener(eventType, callback)
47 | node.addEventListener(eventType, callback)
48 | }
49 | Instead of calling element.addEventListener(), it is better to use eReset() to ensure events are properly managed between page navigations.
Failing to unhook events upon navigation will result in the same events being hooked multiple times to the target element, which can have unexpected consequences and lead to poor memory management.
godocument.config.json is the configuration file for your application. It contains the necessary information to generate your website's routes.
The order of items in godocument.config.json will determine the order of your pages in your website.
Here is the base configuration needed to generate a site using Godocument:
{
3 | "docs": {
4 | "Introduction": "/introduction.md"
5 | }
6 | }
7 | The /docs directory and the /docs/introduction.md file are required for Godocument. Also, the json object "docs" must be named "docs" and the first entry beneath "docs" must be "Introduction": "/introduction.md". Failing to meet these requirements will result in a panic.
The entries in godocument.config.json can either be pages or sections. Let's start with pages.
To denote a page, simply create a key-value pair with the key being the name of the page and the value being the file path to the .md file for the page. You can name pages whatever you would like.
All file paths in godocument.config.json are relative to /docs. This means you do not have to the include /docs in your file paths as Godocument assumes all your markdown files are in /docs.
Here is how you would add a new page to the base configuration:
{
8 | "docs": {
9 | "Introduction": "/introduction.md",
10 | "New Page": "/new-page.md"
11 | }
12 | }
13 | After adding the page to godocument.config.json you will need to create the associated file. From the root of your application, run:
touch /docs/new-page.md
14 | Then, add the following lines to /docs/new-page.md:
# New Page
15 |
16 | I created a new page using Godocument!
17 | From the root of your application, run go run main.go and view the results at localhost:8080.
Sections are named areas of your website which contain a series of pages. Sections can also contain sub-sections. In godocument.config.json, a section can be denoted by creating an object. For example:
{
18 | "docs": {
19 | "Introduction": "/introduction.md",
20 | "New Section": {
21 |
22 | }
23 | }
24 | }
25 | After creating a section, you can add pages within it:
{
26 | "docs": {
27 | "Introduction": "/introduction.md",
28 | "New Section": {
29 | "About": "/new-section/about.md"
30 | }
31 | }
32 | }
33 | You can also add sub-sections:
{
34 | "docs": {
35 | "Introduction": "/introduction.md",
36 | "New Section": {
37 | "About": "/new-section/about.md",
38 | "More Info": {
39 | "Origins": "/new-section/more-info/origins.md"
40 | }
41 | }
42 | }
43 | }
44 | Create the corresponding files and directories:
mkdir /docs/new-section
45 | touch /docs/new-section/about.md
46 | mkdir /docs/new-section/more-info
47 | touch /docs/new-section/more-info/origins.md
48 | Add the following content to /docs/new-section/about.md
# About
49 |
50 | I created a page within a section using Godocument!
51 | Then, add the following lines to /docs/new-section/more-info/origin.md:
# Origins
52 |
53 | I created a page within a sub-section using Godocument!
54 | To test the results, run go run main.go from the root of your application and visit localhost:8080
Godocument does not require you to structure your /docs directory in any particular way, BUT it is highly recommended to have your /docs directory mirror the structure of your godocument.config.json file.
For example, here is a godocument.config.json file which does not follow the proper conventions.
The example below does not follow the recommended conventions for godocument.config.json.
{
55 | "docs":{
56 | "Introduction": "/introduction.md",
57 | "More Info": {
58 | "About": "/about.md"
59 | }
60 | }
61 | }
62 | It does not follow the conventions because /about.md should have a file path which mirrors the structure of godocument.config.json.
To correct the above godocument.config.json make the changes below.
{
63 | "docs": {
64 | ...
65 | "More Info": {
66 | "About": "/more-info/about.md"
67 | }
68 | }
69 | }
70 | Such a change will ensure that the /docs directory mirrors the structure of godocument.config.json, as recommended.
Godocument autogenerates titles based off the keys provided in the "docs" section of godocument.config.json. For example, a key value pair of "Introduction": "/introduction.md" would render a title of Godocument - Introduction when visiting the introduction page.
All pags titles will be prefixed with "Godocument - " until you specify otherwise in the "meta" section of godocument.config.json.
To modify title prefixes, set the following config:
{
71 | ... your "docs" section,
72 | "meta": {
73 | "title": "Custom Title Prefix"
74 | }
75 | }
76 | Doing this will prefix all autogenerated titles with, Custom Title Prefix - .
Air is a binary that provides hot-reloading functionality. It can be installed using:
go install github.com/cosmtrek/air@latest
77 | Just be sure your Go binaries are registered in your $PATH.
All the configuration needed to implment Air properly in Godocument is included in .air.toml.
When running Air, a /tmp directory will be generated. /tmp is already included in your .gitignore and you can disregard it during development.
To enable hot-reloading, go to the root of your project and run:
air
78 | Code blocks are made possible by Prism.
Godocument includes support for all languages supported by Prism. This is to make it easy to get started with your website. However, when you plan to deploy, it is a good idea to go over to Prism's download page and select only the languages used in your application.
When downloading the required languages for your site, you only need to download the .js file and replace /static/js/prism.js with the newly downloaded file. Be sure the file is named, primsm.js.
Godocument uses both Vanilla CSS and Tailwind for styling. If you intend to make changes to the Tailwind classes in your markup, you will need to download the Tailwind binary and run tailwindcss -i './static/css/input.css' -o './static/css/output.css' from the root of your project. Doing so will recompile your /static/css/output.css and adjust to any changes.
The tailwind.config.json file provided in the Godocument repo will contain the proper configuration needed to target all the .html and .go files in your project.
Vanilla CSS is used in Godocument for things like the page layout, scrollbar appearance, and a few other things. All Vanilla CSS can be found at /static/css/index.css.
Godocument makes use of CSS variables to give users more control of their theme. Variables are either viewed as utility variables or element-specific variables.
To adjust the theming for your site, edit the variables found at the top of /static/css/index.css.
Utility variables are not directly used in markup. Rather, they are intended to be used in element-specific variables. Here are the color utility variables for this site:
--white: #fafafa;
3 | --black: #1f1f1f;
4 | --gray-800: #333333;
5 | --gray-700: #555555;
6 | --gray-600: #777777;
7 | --gray-500: #999999;
8 | --gray-400: #bbbbbb;
9 | --gray-300: #dddddd;
10 | --gray-200: #f0f0f0;
11 | --gray-100: #f5f5f5;
12 | --light-gray: #d0d0d0;
13 | --gray: #555555;
14 | --darkest-gray: #222222;
15 | --purple: #ba8ef7;
16 | --dark-purple: #712fec;
17 | --green: #3bec74;
18 | --dark-green: #057d2f;
19 | --pink: #b370b1;
20 | --yellow: #ffea6b;
21 | --dark-yellow: #7f7108;
22 | --orange: #ffa763;
23 | --dark-orange: #c64719;
24 | --blue: #2494da;
25 | --dark-blue: #1b6dbf;
26 | --red: #ff4d3f;
27 | --dark-red: #c82216;
28 | Element-specific variables make use of utility variables. Here are the element-specific variables that control the colors in the codeblocks found on this site:
/* light code blocks */
29 | --code-bg-color: var(--gray-200);
30 | --code-token-property: var(--dark-purple);
31 | --code-string: var(--dark-green);
32 | --code-token-selector: var(--dark-orange);
33 | --code-function: var(--dark-yellow);
34 | --code-keyword: var(--dark-purple);
35 | --code-operator: var(--black);
36 | --code-punctuation: var(--gray-700);
37 | --code-important: var(--dark-orange);
38 | --code-comment: var(--gray-700);
39 |
40 | /* dark code blocks */
41 | --dark-code-bg-color: var(--gray-800);
42 | --dark-code-token-property: var(--purple);
43 | --dark-code-string: var(--green);
44 | --dark-code-token-selector: var(--orange);
45 | --dark-code-function: var(--yellow);
46 | --dark-code-keyword: var(--purple);
47 | --dark-code-operator: var(--white);
48 | --dark-code-punctuation: var(--gray-300);
49 | --dark-code-comment: var(--gray-300)
50 | Godocument makes use of Tailwind's ability to use CSS variables within Tailwind classes. For example, here is the markup for the <header> at the top of this page:
<header id="header" class="flex flex-row justify-between items-center border-b z-30 p-4 sticky top-0 w-full bg-[var(--header-bg-color)] dark:bg-[var(--dark-header-bg-color)] border-[var(--b-color)] dark:border-[var(--dark-b-color)]" style="grid-area: header;">
51 | <div class="header-logo-wrapper flex flex-row shrink-0 items-center w-[250px]">
52 | <img class="logo items-center flex-row" src="/static/img/logo.svg" alt="logo" id="logo">
53 | </div>
54 | <svg class="sun cursor-pointer hidden lg:block shrink-0 dark:lg:hidden" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none" viewBox="0 0 24 24">
55 | <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 5V3m0 18v-2M7.05 7.05 5.636 5.636m12.728 12.728L16.95 16.95M5 12H3m18 0h-2M7.05 16.95l-1.414 1.414M18.364 5.636 16.95 7.05M16 12a4 4 0 1 1-8 0 4 4 0 0 1 8 0Z"/>
56 | </svg>
57 | <svg class="moon cursor-pointer hidden shrink-0 dark:lg:block" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none" viewBox="0 0 24 24">
58 | <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 21a9 9 0 0 1-.5-17.986V3c-.354.966-.5 1.911-.5 3a9 9 0 0 0 9 9c.239 0 .254.018.488 0A9.004 9.004 0 0 1 12 21Z"/>
59 | </svg>
60 | <svg id="bars" class="cursor-pointer block lg:hidden shrink-0" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="28" height="28" fill="none" viewBox="0 0 24 24">
61 | <path stroke="currentColor" stroke-linecap="round" stroke-width="2" d="M5 7h14M5 12h14M5 17h14"/>
62 | </svg>
63 | </header>
64 | Take note of the classes on the <header> element itself. You'll see classes such as bg-[var(--header-bg-color)] or dark:border-[var(--dark-b-color)].
Although the syntax is ugly, it does come with its perks.
You can adjust the colors of the elements on the page using variables instead of having to change the markup for each individual element.
Markdown content is styled using Vanilla CSS. This is done to minimize the amount of text found in .md files. To adjust the styling of markdown content, edit the // markdown styles ------ section of /static/css/index.css.
To change the logo for your site, simply replace /static/img/logo.svg with your logo. There is only one caveat, logos with a large height may shift the navbar in unexpected ways. For this reason, it is recommended to use a logo which is wide, not tall.
During development, the server searches for your favicon.ico at /favicon.ico. When you go to build your static assest, the favicon will be placed in /out/favicon.ico. To change your favicon.ico, simply replace the icon found at /favicon.ico.