Hindsite FAQ

Does Hindsite support themes and skeletons?

Use the Hindsite init command to install website styling, content and structure from existing site templates or from built-in templates.

Why does the serve command sometimes fail a live reload?

Some text editors create temporary and backup files when documents are saved and created, you need to exclude these files from document processing. Failure to do so can result in rebuild false positives and premature watcher reloads.

For example, the Vim editor creates tilda suffixed backup files and temporary 4913 files so you need to add them to the exclude configuration variable in the templates directory root configuration file.

TOML example:

exclude = "*~|4913"

How can I add site search to my website?

An easy way to add a site search feature is to use the Google Programmable Search Engine. For example, the Hindsite built-in blog template includes a Google PSE search page.

Google can take many days to index new and updated Web pages and even then there's no guarantee that they will be indexed. See Get your website on Google.

How do I include Disqus comments in my website?

The recipe described below is taken from the Hindsite built-in blog template. If you initialized your site with the built-in blog template then you already have the Disqus template and steps 3 and 4 below are redundant.

  1. If you don't already have one you need a Disqus account.
  2. Now log into to your Disqus account and register your site. Make a note of your site's Disqus shortname, you need to include it along with some Disqus JavaScript code to your site's generated webpages.
  3. Copy this disqus template definition to a site template file:
    {{define "disqus"}}
{{/*
    If the user `shortname` variable is set and the document `id` is
    non-blank then Disqus comments are inserted.
*/}}
{{if and .id .user.shortname}}
<div id="disqus_thread"></div>
<script>
    var disqus_config = function () {
        this.page.url = '{{.url}}';
        this.page.identifier = '{{.id}}';
    };
    (function() {
        var d = document, s = d.createElement('script');
        s.src = 'https://{{.user.shortname}}.disqus.com/embed.js';
        s.setAttribute('data-timestamp', +new Date());
        (d.head || d.body).appendChild(s);
    })();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
{{end}}
{{end}}
  4. Include the Disqus template in your web pages by adding this line at the end of the HTML body in your document footer template:
    {{template "disqus" .}}
  5. Add a user shortname entry to the site config file and set it to your site's Disqus shortname. TOML example:
    [user]
shortname = "disqus-shortname-goes-here"

That's it, all published documents with a non-blank document id will now include Disqus comments.

How can I customize .date and .modtime template variable formats?

Use the Go Format function. For example:

{{.modtime.Format "Monday, 02-Jan-06 15:04:05 MST"}}

The .shortdate, .mediumdate and .longdate document template variables are simpler and preferable to using .date directly.

How do you configure source code highlighting?

By including highlight.js CSS and scripts in your web pages. For example, see the Hindsite built-in docs.

How can I partition documents into separate categories?

Put them in separate indexes. Indexes are similar to Wordpress categories but they are folder based so you do not have to assign them explicitly.

I want a single page document index

Set the paginate configuration variable to -1 and all indexed documents will appear on the first page.

I want both paginated and single page document indexes

This technique creates a second nested index:

  1. Create a child index with the paginate configuration variable set to -1. For example:
    template/
    posts/
        docs.html           # Paginated document index template.
        all/
            docs.html       # Non-paginated (single-page) document index template.
            config.toml     # paginate = -1
  2. Create a corresponding content child directory and move the content documents into it:
    content/
    posts/
        all/    # Move documents here from posts.

Each index has it's own docs.html HTML template. This technique can be extended to create multiple additional indexes over a the same indexed document set.

Quote the link's href or src attribute with single quotes instead of double quotes, for example:

<a href='foobar.html'>single-quotes skip lint checks</a>

Aren't single-hyphen command options non-standard?

Hindsite follows the Go command single-hyphen convention:

How fast is hindsite?

Hindsite compares more than favorably with Hugo (which bills itself as “The world’s fastest framework for building websites”).

Fully rebuilding a blog site containing 5000 Markdown posts (20MB of Markdown source) revealed that Hindsite is over twice as fast as Hugo (3.14s vs 7.98s). Hindsite's executable is much smaller than Hugo's (8MB vs 53MB) and it consumed less working memory (46KB vs 432KB). Both sites are of comparable complexity.

The benchmark

The benchmarked Hindsite and Hugo sites are available in the downloadable hindsite2-benchmark.zip file (7.0MB):

├── hindsite
│   ├── build/
│   ├── content/
│   └── template/
└── hugo
    ├── archetypes/
    ├── content/
    ├── data/
    ├── layouts/
    ├── public/
    ├── resources/
    ├── static/
    ├── themes/
    └── config.toml

To compare performance, run hindsite and hugo commands from their respective site directories. Here are the build performance statistics measured using the GNU/Linux time command running on Ubuntu Linux 20.04:

Hindsite build

$ /usr/bin/time -v hindsite build
documents: 5005
static: 6
time: 3.14s
        Command being timed: "hindsite build"
        User time (seconds): 3.21
        System time (seconds): 0.85
        Percent of CPU this job got: 129%
        Elapsed (wall clock) time (h:mm:ss or m:ss): 0:03.14
        Average shared text size (kbytes): 0
        Average unshared data size (kbytes): 0
        Average stack size (kbytes): 0
        Average total size (kbytes): 0
        Maximum resident set size (kbytes): 46288
        Average resident set size (kbytes): 0
        Major (requiring I/O) page faults: 0
        Minor (reclaiming a frame) page faults: 13615
        Voluntary context switches: 4956
        Involuntary context switches: 2296
        Swaps: 0
        File system inputs: 0
        File system outputs: 134000
        Socket messages sent: 0
        Socket messages received: 0
        Signals delivered: 0
        Page size (bytes): 4096
        Exit status: 0

Hugo build

$ /usr/bin/time -v hugo
Start building sites … 
hugo v0.99.1-d524067382e60ce2a2248c3133a1b3af206b6ef1 linux/amd64 BuildDate=2022-05-18T11:18:14Z VendorInfo=gohugoio

                   |  EN   
-------------------+-------
  Pages            | 5071  
  Paginator pages  | 2932  
  Non-page files   |    0  
  Static files     |    0  
  Processed images |    0  
  Aliases          |   32  
  Sitemaps         |    1  
  Cleaned          |    0  

Total in 7837 ms
        Command being timed: "hugo"
        User time (seconds): 19.70
        System time (seconds): 1.18
        Percent of CPU this job got: 264%
        Elapsed (wall clock) time (h:mm:ss or m:ss): 0:07.89
        Average shared text size (kbytes): 0
        Average unshared data size (kbytes): 0
        Average stack size (kbytes): 0
        Average total size (kbytes): 0
        Maximum resident set size (kbytes): 432840
        Average resident set size (kbytes): 0
        Major (requiring I/O) page faults: 0
        Minor (reclaiming a frame) page faults: 107285
        Voluntary context switches: 4204
        Involuntary context switches: 9082
        Swaps: 0
        File system inputs: 0
        File system outputs: 332888
        Socket messages sent: 0
        Socket messages received: 0
        Signals delivered: 0
        Page size (bytes): 4096
        Exit status: 0

Performances of both Hindsite and Hugo suffer if the site folders are not excluded from anti-virus real-time protection.

Why did you create hindsite?

The short answer is programmer's hubris; the longer answer has it's genesis in Hugo's complexity.

Prior to writing Hindsite I was using Hugo for blogging. Hugo is an outstanding program, it's chock full of features and has the flexibility needed to build complex static web sites. But features and flexibility come at the price of complexity and a steeper learning curve.

My frustration was not with Hugo but with my brain's ability to retain hard-won working knowledge of Hugo across six months or more between casual use. The amount of time spent relearning (necessitated by my occasional reconfiguration and theme tweak) motivated me to write Hindsite.

Hindsite was designed to be easy to learn and use, it was not designed to compete with Hugo's massive feature set.

The casual-use argument is the same reason my go-to drawing program is Microsoft Paint or KolorPaint and not Adobe Photoshop or The Gimp.