Ask HN: Static site generator that can cope with octopus juggling geysers?

15 points

4 years ago

Intriguing title huh? It is the only way could think to succinctly describe what I need; and I suspect could be useful for other multi-disciplinary, generalist hackers that can turn their hand to any language or project and generate a lot of miscellaneous documenation, code, patches, and shell scripts.

Summary: Wanting a static site generator that (possibly via plug-ins) understands (or can be made to understand) Apache httpd mod-include conditional server-side-include (SSI) directives as an integral part of page content generation.

Over 20+ years I've generated thousands of hacking-focused small (and large) documentation of bug hunts, notes, transcripts, exposés, instructions, shell scripts and more. Most is either in Markdown, hand-edited HTML, or currently on-someone-elses-computer in the form of posts and comments across many sites (including HN) and I intend extracting those to Markdown locally to ensure I have a single source for everything and it cannot go AWOL.

I'm aiming to integrate them into a single static web site hosted by Apache httpd utilising mod-include[0] to do some clever server-side include abstract inclusion in index pages without any text duplication across multiple index pages, and with no use of dynamic server-side or client-side languages (so no PHP or Javascript).

The end result I want is each 'issue' in a single well-formed HTML5 page with semantic elements, embedded meta tags for classifying into one or more categories to enable generation of indexes, overview lists, tag clouds, or whatever.

The aim is to have abstracts (summaries) of issue pages included in the index/overview/category/tag-cloud pages via mod-include by only taking the title and first paragraph. In an index page e.g:

  <body class="index">
  ...
  <!--#include virtual="issue-0001.html" -->
  ...
  <!--#include virtual="issue-0002.html" -->
  ...
  <!--#include virtual="issue-0003.html" -->
  ...

and in the issue pages simply have some conditional server-side include code that determines if the page is being included in another - and if so only include the title and abstract text and not the entire HTML document.

The bonus for the index pages here is to use HTML5 semantic element "<details>" in order to have the browser automatically collapse the details text and show a 'reveal' icon next to it:

  <!--#if expr='v("SSL_LEVEL") -eq 0' -->
  <DOCTYPE html>
  ...
    <style>
     details:
    </style>
    </head>
    <body>
  <!--#endif -->
     <details <!--#if expr='v(SSL_LEVEL") -eq 0' -->open<!--#endif --> >
      <summary><h1>Issue title<h1></summary>
      <p>First paragraph of article containing the summary</p>
     </details>
  <!--#if expr='v("SSL_LEVEL") -eq 0' -->
   ...
   </body>
  </html>
  <!--#endif -->

This fragment adds the "open" attribute to "<details>" when the entire page is requested so the title and first para are shown by default. The index page has CSS to reduce the impact of the "<h1>" in the "<summary>"; e.g:

  .index details summary h1 {font-size: 14pt; font-weight: normal;}

I've already added code to mod-include to detect and conditionally react to nested includes after dealing with a bug in its existing handling[1].

I've recently chosen Jekyll for a variety of reasons; mostly because it focuses on generating HTML+CSS without any Javascript overload and has a large number of plug-ins and themes of various qualities to hand which may be a basis for me adding the feature I want. I'm open to changing if there's something that can (more easily) do what I require.

[0] https://httpd.apache.org/docs/current/mod/mod_include.html

[1] https://bz.apache.org/bugzilla/show_bug.cgi?id=66243

 <DOCTYPE html> ... <style> details: </style> </head> <body>  <details open > <summary><h1>Issue title<h1></summary> <p>First paragraph of article containing the summary</p> </details>  ... </body> </html> 

23 comments

23 comments