Weave Software

This Grovelife website is written in Markdown and uses Ink, to convert source texts into html. The website is assembled with Weave, which is custom software that I have written in the Swift computer language.

The resources that it uses:

  • The Weave static website builder software
  • In a source directory
    • Source texts are converted by Ink into html code for use in structured html files.
    • Templates for html:
      • the top-level html documents ("templates")
      • components of documents (for markdown to html) content ("inserts")
  • In the site directory
    • Images and other media files
    • CSS document(s)
    • a javascript file

About it

Each source text file is converted into a page on the website. It may be linked by name from other pages:

  • Linking between pages on the site uses a modified form of Markdown reference links. Note:
    • A normal Markdown reference link is of the form [text of the link][refName].
    • It normally expects a line elsewhere in the same source document to have the refName and the associated link.
    • Conveniently if that link is missing, the unmodified refName text remains in the URL.
  • To link between pages on the site:
    • put the name of the target page in for the refName with a : (a colon) in front of it (no file extender)
    • but don't put a matching ref line in the document
    • e.g. [text of the link][:targetPageName]
  • In the case a .pdf file is to be linked, the form is slightly different
    • put the name of the .pdf file in for the refName with a ! in front of it (no file extender)
    • again, don't put a matching ref line in the document
    • e.g. [text of the link][!targetPdfName]
  • Images use the standard markdown link format, however put in (only) the name of the image without path or extender.

 

Template and insert files are text files with the text "_template" or "-insert" in the name. A template is expected to already be in html; an insert is to be markdown which will be converted into html. A web page is constructed from these components starting from a top-level template. (The default template is named "base_template"). This template is to have one or more insert sections of the form {{insert_name}}.

  • static inserts come from insert template files
  • certain dynamic inserts are produced by the Weave software
  • source pages can supply inserts in section structures

Source text files can produce content other than the main section content. It does this by marking sections in the source content

  • a preview from the main content of a page.
    • It is to be marked with a "/preview" line. What is above this line will be available for other pages to use as an insert.
    • if nothing is on the line after the preview marker then
      • In the original page source, the /preview line will be removed and replaced with a short horizontal rule.
    • if "-exclude" follows the marker then
      • Only the material after the marker will be put in the main content of the page. This probably requires duplicating some portion of the preview text, but it gives more control of where the preview break occurs.
    • The preview can be inserted into other pages with a line entry of the form {(preview:xxx)} where xxx is the page name.
  • inserts and side column content
    • these are marked with a /annex-xxx line where xxx is local or export
    • the name for the content follows on the same line. (No whitespace.) It will be saved for use if it has a name.
    • export produces inserts that may be used by other pages.
    • local produces inserts that may be used by the source page or its sub-pages
    • these items are removed from the main content source
    • Inserts may be used in a template or content section with text in the form of {{insert_name}}.
  • side column content
    • This is obtained from local and external inserts.
    • Any local insert item with side in the name will be added to the side column
    • External inserts to be added to the side may be listed by name in a metadata side_items item. Multiples may be listed if they are comma-separated
    • There are two cases where a navigation insert is created and inserted automatically
      • for all sub-pages of a page
      • for all blog preview aggregation pages
  • additional html pages as sub-pages of a page.
    • These are marked with a /newpage Sub Page Title line
    • In the original page, the content will be only up to the first /newpage
      • There is one special case: If there is no content before the first /newpage, then the main page content starts after the /newpage. This supports custom names for the main page in the side navigation insert.
    • sourcePageName_SubPageTitle   will be the form of the name of sub-pages after the first page.
    • Main Page Title - Sub Page Title   will be the form of the page & sub-page title
    • If there is nothing on the line to the right of the /newpage, the sub-page will be given a numbered name and title
    • The sub-pages will have content between the /newpage lines up to the end of the source text

The content of other pages in the built website is accessed either by a page link or by inserting a page preview

Using Metadata

The website source content files are expected to have a metadata section at the top in the form:

---
label: value
another_label: another value
---

Main markdown content text...

The Weave software supplies some hard-coded default metadata items. The metadata from the top of the page source file is added to this (replacing the defaults if matching).

There are a few recommended page metadata items.

  • title : The title for the page. Missing this it will use the file name.
  • date : The posting date for the page, indicated at the bottom.
    • Missing this, it will use the file create date.
    • Will be used especially for dating blog entries.
    • If the value is blank, then the create date won't be put on the page. This feature would be used for top-level pages where the post date is not relevant. The date can be recorded in the source file, but call it "hide_date" (for example) instead.
  • update : An content update date, indicated at the bottom of the page.
    • Missing this, it will use the file modify date.
    • If the value is blank, then the update date won't be put on the page.
  • group : The top-level group the page is assigned to. This associates it to a top-level navigation group.
    • Missing this, it will be assumed to be in the "blog" group (but only for navigation handling).
  • blog : Which of multiple blogs the page is in.
    • Existing and not specified otherwise, the page will be assumed to be in the blog group (for navigation handling)
    • Existing but having blank content, it is assumed to be "blog: blog".
    • Existing and matching content to the page name, it will be the top-level blog page

Other items:

  • out_name : replaces the name taken from the name of the source file, to be used for the name of the output .html file
  • path : replaces the default relative path to where the .html file will be written
  • tags : words (whitespace separated) that indicates topics the page is associated with
  • template : replaces the default page template
  • side_items : a comma-separated list of names of inserts for the side column, taken from the common (external) insert collection

Notes in pages

Footnotes are common in documents, but are difficult for the reader to navigate when they are far apart on the page. Instead Weave supports hidden notes in the main content. These notes are markdown like the rest of the source file text.

A javascript file has a toggleNote function to hide and unhide notes when a button inline in the text is clicked. Weave creates the button html and it inlines the notes. The .css file hides the notes by default. The buttons use a .btn class (for formatting), and the notes used a .note class (which sets them to hidden).

Write notes anywhere in the source page (but usually at the bottom). They are to be marked with a line before the note text of the form [note id="xxxIdentifier"]. After the text of the note can be another note identifier for another note. After the last note, there needs to be at least a [note] end marker. These will be removed out of the page content by Weave.

In the text where a note button is desired, add [show id="xxxIdentifier"]. The xxxIdentifier can be any identifying text and must match between the two.

Weave will insert the note into the page text after the paragraph containing the note button. (That is, after the next html </p> characters.) (If this automated location is not acceptable, insert [placeNote id="xxxIdentifier"] in the source text where the note should be inserted.)

Notes and tips:

  • This note removal and insertion is done after the source has been converted to html.
  • If a trailing [note] is not put after the last note, unexpected html will result (because the last note will consume to the end and remove some div closing tags).
  • Note that if a line has two or more spaces at the end, Ink will put a <br> at the end instead of a </p>. This would cause unexpected note placements. Remove the extra spaces.
  • The Note show/hide buttons are removed from preview inserts.

Starting a website

  • Develop a design language for the webiste
  • Develop how the website will built. This means a basic .html mockup and the .css for it.
  • Convert the mockup into a template
    • The template will need to be named "base_template.txt" - this is from the defaults at the top of the Weave main.swift file. (But this default can be replaced per-page via the metadata.)
    • There is a general concept of a set of top-level pages associated with groups of content. For instance the main landing page might be in the "home" group, the main blog page and blog items might be in the "blog" group. This idea is supported for top-level navigation bar highlighting.
      • The non-highlighted menu items should have a css class name of "xxx_group", as for instance "home_group".
      • When the page is assembled, the text of the page's associated group will be substituted with "here".
      • No class is required to exist in the .css for the "xxx_group" names, but a "here" class styling should exist to highlight the group that was selected.
    • The template will need an insert placeholder for the page's content. This is to be {{main_content}} in the template where the content is to be inserted.
    • For other insert items in the template, when a matching metadata name is found, the insert will be replaced with the metadata value.
      • If matching data is not found, the braces will be removed from around the insert text.
    • The template can have an insert placeholder for side-bar content for the page. This is to be {{side_content}} in the template where the content is to be inserted.
      • Selection of the side content comes from entries in the metadata for the page.
      • It will first look for an entry named "side_items" in the metadata of the page.
      • Failing this, it will look for a metadata item called "xxx_sideDefault", where the xxx is the name of the top-level group. (This might be supplied as a global metatdata item.)
      • The data from this metadata will be used as the name of an insert to be substituted for the insert placeholder. Any groups without either of these defaults will replace the insert with an empty string.
  • Make content source pages for at least the top-level groups.
  • Create additional content. Blog items will be automatically linked into the blog lists and previews. Other items will need to be linked manually from other pages.

Addtitional tips

  • The Ink Markdown converter seems to expect that all html tags are closed. If not, it behaves strangely, producing unexepected conversion results (even with empty tags). It seems to be satisfied with putting a closing slash in the tag: like <hr /> and browsers are OK with that too.
  • Two spaces at the end of a sentence in Markdown produces an HTML break rather than a paragraph (even though this is not visible). This produces unexpected results from Ink with mis-interpretatation of following lines until there is a paragraph close. Remove the spaces unless specifically desired.
  • Page preview inserts are disallowed for blog posting pages or pages that divide into sub-pages. These are essentially expected to have their own content.
2020-12-23 updated 2021-05-13   © 2021 Larry Grove