HACKER Q&A
📣 iam-TJ

Static site generator that can cope with octopus juggling geysers?


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:

  
  ...
  
  ...
  
  ...
  
  ...
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 "

" in order to have the browser automatically collapse the details text and show a 'reveal' icon next to it:

  
  
  ...
    
    
    
  
     
open >
      
Issue title

      
First paragraph of article containing the summary

     

  
   ...
This fragment adds the "open" attribute to "
" 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 "

" in the ""; 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

  👤 jerf Accepted Answer ✓
I don't really understand the question. Blasting text values into files wholesale is what static site generators do. The web server is operating on the textual values on the disk. You shouldn't need "support" for this, you just use the static site generator to output the desired text into the mass of files it produces. You seem to already know what text you want on the disk, and that seems like 80% of the problem.

I mean, if you really want to add a custom function or two to Jekyll you can, but you hardly need to wait around for "support" for this.

You may be asking for a template that has this built in, but you're just as well off to take an existing template you like and modify the text it is generating than to wait around for someone else to do it.

If it seems like the static site generator doesn't "support" this it's because it's just so "what it does" that there isn't any documentation for how you'd specifically put SSI tags into a site, because that'd just like expecting specific documentation for how you put

tags into a website. It's just what it does already.

👤 onion2k
I honestly can't think of a reason why you'd go to all the effort of using a static site generator and not generate complete pages. What benefit is there in using mod_include?
👤 vinaypai
Seems like you are using a dynamic server-side language, but it's just in mod-include's SSI language instead of something more conventional.
👤 pentestercrab
One idea, maybe using file instead of virtual will avoid the bug and not require your added code.
Also, be careful of any moves to supporting dynamic content as Server Side Includes can (sometimes?) lead to code exec even with IncludesNoExec.
👤 alanbernstein
I don't really understand what you're looking for, but the comments lead me to think of one thing that might be a little relevant, if not directly useful for you.

In mediawiki it's called transclusion. There is a markdown extension with similar functionality called multimarkdown. I looked into it briefly for a project once, but ended up going with basic markdown instead to keep maintenance and content writing as simple as possible.

https://en.m.wikipedia.org/wiki/Help:Transclusion

https://fletcherpenney.net/multimarkdown/

👤 xani_
Making static content that is tied to work only if you have specific web server with specific plugin seems... counter-productive at the very least

> 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].

and even more if you need to patch the web server to even make it work.

That being said jekyll include syntax is quite rich https://jekyllrb.com/docs/includes/ so you'd probably just do fine with it and minimal legwork

👤 corobo
I think this is how PHP was invented
👤 colanderman
You can do this 100% statically using XSLT, which is processed client-side.

Honestly, I'm surprised web browsers continue to support XSLT, as I've never seen it used, but I've used it here [1] for a while seemingly without issue.

[1] https://www.bostonesperanto.org/

👤 encryptluks2
Just use Hugo or some normal tool and move on.