Project Skeleton

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

Folder Structure #

  • /.butterflyBuild: compiled output

  • /src: contains content that needs to be converted or compiled

    • /style: sass markup that is compiled to /public/__bbbfly/style
    • /pages: contains pug/html/markdown that is compiled to public, preserving the directory structure - like classic html path shit
    • /md_templates: templates that are used by the markdown parser
    • /components: pug components that can be included into pages and are compiled to /public/__bbbfly/components for use on the client
    • /public: as-is assets;

Markdown File Specification #

Template #

  • A pug template that can be used by markdown files in /pages
  • The compiled content is passed in the converted local
  • Make sure to use a ! to tell pug to include the raw content
  • other passed locals:
    • url: url this file will have
    • articles: article cache
    • author: author
    • time Date Object for date defined in header
    • vars: Custom Object defined via markdown file header
    • docInfo: DocInfo (obtained by HTML scraper)
    • functions isSubpath and getFolder for working with the article cache

Markdown File #

  • It’s just markdown except:

  • Links may be converted to embeds

  • Anchor tags may be included

  • hopefully custom styles at some point

  • Can include JSON metadata in a md comment on the first line (“Header”)

    • [//]: # '{"template": ""}' 
    • template: String – specifies the name of the pug template used (or default.pug)

    • tags: String[] – list of tags used to group of documents

    • vars: Object – values will be inserted into pug locals
      lang: String, can be “de”, will sometimes do something

    • parserOptions: Object - may in future set the parser options





Datatypes #

document info #

  • title, description, fulltext
  • sections: Array of section objects
    • text: Headline of this section
    • anchor: Tag, used to skip through the page
    • lvl: heading level
    • sub: Array of subsections

article cache #

  • root is a folder object for /pages
  • Folder Object:
    • url: Url of this folder
    • articles: Array of article objects
      • url: URl of this article
      • author: author
      • time Date Object for date defined in header
      • template, vars, parserOpts
      • includes all properties from DocInfo
    • folders: Array of folder objects
    • series: bad idea object that’s always empty

author #

  • defined in /src/authors.json
    • array of objects outlined below
  • displayName - name that may be displayed by pug file
  • avatarUrl - should be a url pointing to a (square) image, that may […]
  • description - description that may […]

About me


Euer charismatischer Gastgeber hier auf Konrad Webseite.