source

this page contains the Pyra0 code that's used to generate this website . the full source repository is on SourceHut .

design philosophy

• HTML is the best format for pages , now that i've solved the readability problem . it has the most comprehensive set of semantic elements , is natively supported by the browser , and there are many high-quality libraries for modifying its structure , such as Nokogiri , Floki , or Lambda Soup . formats like Markdown aren't worth the additional complexity of converting them
• write the generator from scratch . frameworks are too cumbersome to work around if you want highly customized page generation
• creating new pages should be easy . automatically insert the title from the filename so you don't need to write any HTML except for the content
• structure content as a wiki instead of a blog . wikis are expected to be timeless and highly edited , and have a freer organizational structure . placing every page at the root of the site allows restructuring without breaking URLs
• don't use too many navigation features . this site used to have series , footnotes , and tags , in addition to the table of contents and backlinks that remain , but it felt too cluttered . too many features will burden the mind more than it aids navigation
• fast build process . under a second , ideally
• achieve accessibility through simplicity

generator.nv

- include file: ../pyra0/libraries/ruby.nv
- include file: ../pyra0/libraries/nokogiri.nv

- get html for each page
- collect backlinks
- render backlinks
- insert table of contents
- insert source code
- wrap each page
- output the website
- copy the static assets
- generate source code graph
- create tar archive


* get html for each page
  - get files in pages folder - get page data

| get page data * name: Name * html: Html
  - pages: Name Html

| get page data * got files: File
  - get base name of File -> name
  - read html fragment from File -> html

* get page data


| collect backlinks for Page Html
* title: Title * destination: Destination
  - backlink to Destination: from Page with Title

| collect backlinks for Page Html
* found elements: Link
  - get content of Link -> title
  - get attribute href of Link -> destination
  - switch tag of Link to a
  - append .html to Link href
  - set id to content of Link

* collect backlinks for Page Html

| collect backlinks * pages: Page Html
  - find elements with tag ba in Html
  - collect backlinks for Page Html
  - seen: Page Html

* collect backlinks - reset pages


| render backlinks for Page Html
* backlink to Page: from Source with Title
| list: List
  - found backlink for: Page
  - append element Item to List
  ^ item = "
      <li>#{source.gsub '-', ' '}:
        <a href='/#{source}.html##{title.gsub ' ', '-'}'>
          #{title}
        </a>
      </li>"

* render backlinks for Page Html * list: List
* found backlink for: Page
  - append element Result to Html
  ^ result = "
      <div class='backlinks'>
        <h2>backlinks</h2>
        #{list}
      </div>"

* render backlinks for Page Html * list: List

| render backlinks * pages: Page Html
  - create element ul in Html -> list
  - render backlinks for Page Html
  - seen: Page Html

* render backlinks - reset pages


- no toc: index
- no toc: wiki
- no toc: projects
- no toc: about

| move * direction: down * list: List * position: Position
  - position: List
  - append element List to Position

| move | direction: down | html: Html
  - create element ul in Html -> list

| move * direction: up * parent: Parent * position: Position
  - position: Parent

| move | direction: up | position: Position
  - get parent of Position -> parent

* move

* update level * comparison: less
  - move - direction: down

* update level * comparison: greater * times: Times
  - put up on direction Times times - move

* update level * comparison: equal

| update level * change: Change
  - compare Change and 0 -> comparison

| update level * new level: Level * last level: Last
  - last level: Level
  - Last minus Level -> change and times

| update level | heading: Heading
  - get level of heading Heading -> new level

* add heading to list
* heading: Heading | position: Position
  - set id to content of Heading
  - append element Element to Position
  ^ element = "
      <li><a href='##{heading.content.gsub ' ', '-'}'>
        #{heading.content}
      </a></li>"

* insert toc element
* comparison: greater * html: Html * toc: List
  - insert Table before children of Html
  ^ table = "
      <details class='toc'>
        <summary>table of contents</summary>
        #{list}
      </details>"

* insert toc element * comparison: Other

| insert toc element * count: Count
  - compare Count and 2 -> comparison

| insert toc element | toc: List
  - get amount of children of List -> count

| process headings * found elements: Heading
  - heading: Heading
  - update level
  - add heading to list

* process headings

| insert table of contents | no toc; Page * pages: Page Html
  - seen: Page Html

| insert table of contents * pages: Page Html
  - seen: Page Html
  - last level: 2
  - html: Html
  - create element ul in Html -> toc and position
  - find elements with tag h2,h3,h4,h5,h6 in Html
  - process headings
  - insert toc element

* insert table of contents - reset pages


* insert source code * container: Container * content: Content
  - set content of Container to Content

| insert source code | pages; source Html
  - find element with id #generator in Html -> container
  - get file content of generator.nv -> content


* find elements in wrapper | wrapper: Wrapper
  - find element with tag main in Wrapper -> main
  - find element with tag title in Wrapper -> title
  - create heading
  - set wrapper title

* create heading | page: index

* create heading | page: Page | main: Main
  - append element Header to Main
  ^ header = "<h1>#{page.gsub '-', ' '}</h1>"

* set wrapper title * page: Page * title: Title
  - set content of Title to Text
  ^ text = "eevie nebulæ: #{page.gsub '-', ' '}"

* wrap Page Html * main: Main * wrapper: Wrapper
  - append element Html to Main
  - seen: Page Wrapper

| wrap each page * pages: Page Html
  - page: Page
  - read html from wrapper.html -> wrapper
  - find elements in wrapper
  - wrap Page Html

* wrap each page - reset pages


* output the website
  - ensure site directory exists
  - output each page

| output each page
* pages: Page Html
  - write file Path with content Html
  ^ path = "site/#{page}.html"

* output each page


* copy the static assets
  - copy files static/. to site
  - copy files /home/eevie/files/srht/yarnstar/dist/. to site/yarnstar
  - copy files /home/eevie/files/srht/miraquad/artifact/web/. to site/miraquad
  - copy files /home/eevie/files/srht/pyra0/examples/axowotw/. to site/axowotw

* generate source code graph
  ^ `lua ../pyra0/pyra.lua graph generator.nv | dot -Tsvg > site/img/source_graph.svg`

* create tar archive
  ^ `cd site && tar -czvf eevie.dev.tar.gz *`


| reset pages * seen: Page Html
  - pages: Page Html

* reset pages

graph visualization