published by Konrad Thursday, the 8th July of 2021 (CET)

These docs are generated using a custom Build tool i made!
The tool renders markdown files into templates and provides a client-side search function.
While i want to use this system for a small blog in the future, i currently just have the tool’s own documentation on here
Please don’t bother reading it!! The tool is not ready to be distributed anyway!

Anyway, this template looks quite good, doesn’t it?
I’m most proud of how well the sidebar works at the moment, look how sexy it is.
I still need to add custom styles to the markdown parser for more flexibility.

Generation #

These “Documentation” Pages are statically generated from Markdown and Pug (Html templating) Files.
To build the site, generate.js is run, which copies html and compiles pug files located in /src/pages to /public.
The directory structure is preserved, allowing easy url definitions through folder names.

Image of the folderstructure

Sass files in /src/style are also compiled to /public/__bbbfly/style,
Pug files in /src/components are compiled to /public/__bbbfly/components and can be imported and used in the browser
Just load the script file, the function will be called render_component_[filename]

generate.js won’t delete files already located in public, allowing you to manually place files into the /assets folder for example
(html files in /public may be overridden by files in /src/pages though, and when the filesystem watcher detects deletion of a /pages file, the corresponding file in /public will be deleted)

Markdown #

Markdown files obviously require a template to define design and control elements such as sidebars, headers, footers, etc.
Thats why you can place pug files into /src/md_templates, and include a json object in the first line of a markdown file:

[//]: # '{"template": "listsidebar", "vars": {"scope": "docs"} }'

This json object can define the template, variables to be passed into it (in this case, the root directory for the sidebar to your left:) )
and other Information outlined here

Article/Blog System, future Plans #

“Well, that’s neat and all”, i hear you say, “but how does this qualify as a blog system”???
And you’d be right. There are a few features i’d want for a simple blogging tool:

  • Search through Articles ✅
  • Suggestion of Articles
  • Tree View for Articles ✅
  • Display latest Articles

As the foundations for all of these features, an index of all articles or pages needs to be generated.
After the compilation step, the generated HTML is scraped for a title, a description, a tree of h1, h2, h3 sections and the full text without formatting for search.
All of this information for every page is saved as a json file, that you can view here

This object is passed to every pug file and the markdown templates, and can then be displayed as the tree view you can see to your left.
I haven’t implemented search, suggestions and a system to implement timestamps yet, but from this foundation it shouldn’t take me that much more time.

articleCache.json is public, so that a browser can be scripted to do the search-stuff on the client side.
This is important for me, since the site lives on Github pages. Maybe if i get my own server, i’ll do secret shit that will require a way to be excluded from the public search index.

I will, when i’m done, probably create an electron.js heroku-app for a more user-friendly process to add articles,
regenerate the site and push both the sourcefiles and the the output to their respective git repos.
(maybe with an option to post the link to twitter)

I’m kinda hyped this will be great

About me


Euer charismatischer Gastgeber hier auf Konrad Webseite.