Move to custom SSG instead of eleventy.

2023-03-04 22:36:08 -05:00
parent 31bb42e985
commit f42225bd13
59 changed files with 337 additions and 1784 deletions
--- a/docs/pages/about.tce
+++ b/docs/pages/about.tce
@@ -0,0 +1,253 @@
+layout layout.njk
+title About - Terrace - A simple structured data language
+description
+  A simple structured data syntax for configuration, content authoring, and DSLs.
+  Terrace gets out of your way to let you just write
+
+Section dark
+  class flex flex-col md:flex-row gap-16
+
+  Block
+    class w-full lg:w-1/3
+    TableOfContents
+
+  Block
+    class max-w-prose
+
+    Heading 1 About Terrace
+
+    Markdown
+      Terrace is a tiny system for storing data in human-friendly text files.
+
+      It allows you to mix all sorts of text and data formats together in an intuitive way without getting caught up in syntax pomp and ceremony.
+
+    CodeBlock terrace
+      title An Essay on Rockets
+      date 2022-02-22
+      by John Doe
+
+      heading The ideal rocket equation
+
+      equation LaTeX
+        \Delta v=v_{\text{e}}\ln {\frac {m_{0}}{m_{f}}}=I_{\text{sp}}g_{0}\ln {\frac {m_{0}}{m_{f}}}
+
+      markdown
+        A fundamental equation in astrophysics, the *ideal rocket equation* describes the total potential velocity of an idealized vehicle propelled by expelling some of its own mass.
+
+      ...
+
+    Markdown
+      class prose-invert
+      You can use Terrace to write documents, web pages, configuration files, data storage, or whatever else you come up with!
+
+      [This page](https://git.thederf.com/thederf/Terrace/src/branch/main/docs/src/about.tce) is written using Terrace!
+
+Section light
+  class flex flex-col md:flex-row gap-16
+
+  Block
+    class w-1/3
+
+  Block
+    class max-w-prose
+
+    Heading 2 Background
+
+    Markdown
+      Terrace was originally envisioned out of frustration at the massive usability gulf for embedding custom blocks in simple, human-friendly markup formats such as [Markdown](), and capable but complex block-based systems such as [Project Gutenberg](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/writing-your-first-block-type/) and [Editor.js](https://editorjs.io/saving-data/).
+
+    Heading 3 The Complexity Problem
+      class mt-8 mb-4
+
+    Markdown
+      **A simple markdown document:**
+
+    CodeBlock markdown
+      # My Page Title
+
+      Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad.
+
+      1. Magna id sint consequat quis esse tempor.
+      2. Veniam eu id esse occaecat eu.
+      3. Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua.
+
+      [Put my-custom-component here somehow]
+
+      Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim.
+
+    Markdown
+      **That same document in a *simplified* Editor.js schema:**
+
+    CodeBlock javascript
+      class max-h-[500px] overflow-y-auto
+      [
+        {
+          type: "header",
+          data: {
+            level: 1,
+            text: "My Page Title"
+          }
+        },
+        {
+          type: "paragraph",
+          data: {
+            text: "Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad."
+          }
+        },
+        {
+          type: "list",
+          data: {
+            style: "ordered",
+            items: [
+              "Magna id sint consequat quis esse tempor.",
+              "Veniam eu id esse occaecat eu.",
+              "Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua."
+            ]
+          }
+        },
+        {
+          type: "my-custom-component",
+          data: {
+            option1: "value",
+            option2: "value",
+            text: "Text"
+          }
+        },
+        {
+          type: "paragraph",
+          data: {
+            text: "Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim."
+          }
+        }
+      ]
+
+    Heading 3 MDX & MDC
+      class mt-16 mb-4
+
+    Markdown
+      Other attempts, such as [MDX](https://mdxjs.com/) and [MDC](https://content.nuxtjs.org/guide/writing/mdc/) have been made to solve this problem, allowing you to incorporate complex content *inside* markup documents.
+
+      However, they suffer from a number of problems:
+
+      1. Tightly coupled to the JavaScript ecosystem
+      2. Lock you out of other markup formats, such as [AsciiDoc](https://asciidoc.org/)
+      3. Difficult to parse - Markdown was not intended as a general-purpose syntax
+      4. Data can't be extracted from markup without rendering the entire document to HTML
+      5. Ugly. Just look at this:
+
+    CodeBlock markdown
+      # My Page Title
+
+      Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad.
+
+      1. Magna id sint consequat quis esse tempor.
+      2. Veniam eu id esse occaecat eu.
+      3. Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua.
+
+      [MDX Example]
+      <MyCustomComponent option1={{'value'}} option2={{'value'}}>
+        Text
+      </MyCustomComponent>
+
+      [MDC Example]
+      ::MyCustomComponent{option1="value", option2="value"}
+        Text
+      ::
+
+
+      Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim.
+
+    Heading 3 Terrace Prototype
+      class mt-16 mb-4
+
+    Markdown
+      I first attempted to solve this problem using an [S-Expression](https://en.wikipedia.org/wiki/S-expression)-based syntax for defining blocks.
+
+    CodeBlock lisp
+      (heading
+        (level 1)
+        My Page Title
+      )
+
+      (markdown
+        Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad.
+
+        1. Magna id sint consequat quis esse tempor.
+        2. Veniam eu id esse occaecat eu.
+        3. Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua.
+      )
+
+      (my-custom-component
+        (option1 value)
+        (option2 value)
+        Text
+      )
+
+      (markdown
+        Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim.
+      )
+
+    Markdown
+      While quite flexible and clean-looking, problems became apparent with handling whitespace and escaping parenthesis in text.
+      The parser quickly became much more extensive than initially envisioned.
+
+      Nevertheless, it proved the concept that cleanly combining functional blocks and markup text was quite reasonable.
+
+      Not long after, I stumbled upon [Tree Notation](https://treenotation.org) by [Brek Yunits](https://www.breckyunits.com/). Playing around with it, the potential of just *getting rid of the parenthesis* was quite apparent. Simpler syntax for humans to write, and far less work required for parsing & escaping since the only control characters are newlines and spaces:
+
+    CodeBlock terrace
+      heading My Page Title
+        level 1
+
+      markdown
+        Occaecat fugiat est ullamco aliqua ea dolor nostrud. Reprehenderit nisi minim sit commodo deserunt ullamco deserunt aute ex exercitation Lorem deserunt ad.
+
+        1. Magna id sint consequat quis esse tempor.
+        2. Veniam eu id esse occaecat eu.
+        3. Minim commodo nostrud eiusmod excepteur ea sint in enim esse aliqua.
+
+      my-custom-block
+        option1 value
+        option2 value
+        Text
+
+      markdown
+        Dolor adipisicing amet aliquip nulla occaecat Lorem excepteur veniam. Voluptate pariatur sint anim tempor aliquip in. Id nulla est irure officia occaecat enim.
+
+    Markdown
+      Ultimately though, using Tree Notation still proved too messy. After working with the grammar system and spreadsheet-style data model for a good while, my gut said all this use case needed was a simple line-based parser.
+
+      I started Terrace to implement a similar syntax, but with the following goals:
+
+      1. Make as few decisions as possible for the user
+      2. Be as fast, tiny, and light on resources as possible
+
+      Six or seven parser rewrites later, it finally works mostly how I envisioned it. :)
+
+Section dark
+  class flex flex-col md:flex-row gap-16
+
+  Block
+    class w-1/3
+
+  Block
+    class max-w-prose
+
+    Heading 2 Development Goals
+
+    Markdown
+      class prose-invert
+      Terrace development is guided by the following goals.
+
+      - **Tiny, primitive core - no “framework”**
+        - Use the most boring patterns possible for implementing the core library.
+        - Avoid dependencies
+        - Easily port Terrace in any language or environment
+      - **Avoid dynamic allocation**
+        - Since we can work directly off of string slices without the need for ASTs and escaping systems, might as well avoid dynamic allocations altogether!
+      - **Minimize assumptions**
+        - Let people use Terrace as a building block for all sorts of languages
+
+      Make note of this before submitting change requests. If your changes don't fit these goals, they may be denied. In which case, you could try building a separate library on top of the Terrace cor.
+
+    Footer
--- a/docs/pages/index.tce
+++ b/docs/pages/index.tce
@@ -0,0 +1,204 @@
+layout layout.njk
+title Terrace - A simple structured data language
+description
+  A simple structured data syntax for configuration, content authoring, and DSLs.
+  Terrace gets out of your way to let you just write
+
+Section light
+  class pt-24 flex flex-col gap-16 md:flex-row lg:gap-48
+  Block
+    class flex flex-col gap-8 w-full items-start
+    Logo light
+      class hidden lg:flex
+
+    Markdown
+      class prose-ul:list-none
+      A simple structured data syntax for
+        - **Configuration**
+        - **Content authoring**
+        - **DSLs**
+
+      Terrace gets out of your way to let you
+        - **just write**
+    Button primary
+      href /docs/javascript/#getting-started
+      Get Started
+
+  CodeExample
+    height 350px
+    terrace
+      title Terrace - A simple structured data language
+      description
+        A simple structured data syntax for configuration, content authoring, and DSLs.
+        Terrace gets out of your way to let you just write
+      markdown
+        A simple structured data syntax for
+          - **Configuration**
+          - **Content authoring**
+          - **DSLs**
+
+        Terrace gets out of your way to let you
+          - **just write**
+    json
+      {
+        "title": "Terrace - A simple structured data language",
+        "description": "A simple structured data syntax for configuration, content authoring, and DSLs.\nTerrace gets out of your way to let you just write",
+        "markdown": "A simple structured data syntax for\n  - **Configuration**\n  - **Content authoring**\n  - **DSLs**\n\nTerrace gets out of your way to let you\n  - **just write**"
+      }
+    yaml
+      title: Terrace - A simple structured data language
+      description: |
+        A simple structured data syntax for configuration, content authoring, and DSLs.
+        Terrace gets out of your way to let you just write
+      markdown: |
+        A simple structured data syntax for
+          - **Configuration**
+          - **Content authoring**
+          - **DSLs**
+
+        Terrace gets out of your way to let you
+          - **just write**
+    toml
+      title = "Terrace - A simple structured data language"
+      description = """
+      A simple structured data syntax for configuration, content authoring, and DSLs.
+      Terrace gets out of your way to let you just write"""
+      markdown = """
+        A simple structured data syntax for
+          - **Configuration**
+          - **Content authoring**
+          - **DSLs**
+
+        Terrace gets out of your way to let you
+          - **just write**"""
+
+Section dark
+  Heading 2 Uses
+
+  Block
+    class flex flex-col space-between gap-16 md:flex-row lg:gap-48
+
+    Block
+      class max-w-prose
+      Block
+        class flex gap-4 items-center mb-4
+        Icon settings
+        Heading 3 Configuration
+          class mb-0
+      Markdown
+        Terrace’s concise syntax (or lack thereof)
+        makes it a great fit for configuration files.
+        Less verbose than JSON without the wild unpredictability and hidden syntax pitfalls that come with YAML.
+
+        If you wish, you can build in your own input validation and type casting while parsing configuration files.
+
+    Block
+      class max-w-prose
+      Block
+        class flex gap-4 items-center mb-4
+        Icon feather
+        Heading 3 Content Authoring
+          class mb-0
+      Markdown
+        An unopinionated, indent-based syntax allows fulls blocks of plain-text or markup languages (such as markdown) to be embedded inside of Terrace documents.
+
+        This enables effortless mixing of data, prose, and functional blocks in human-written documents. No more need for clumsy frontmatter or custom Markdown extensions!
+
+    Block
+      class max-w-prose
+      Block
+        class flex gap-4 items-center mb-4
+        Icon code
+        Heading 3 Domain-Specific Languages
+          class mb-0
+      Markdown
+        Terrace documents, at their core, are effectively their own AST (Abstract Syntax Tree). Every time you parse a Terrace document you’ve essentially parsed your own DSL.
+
+        The core libraries are designed with this in mind, exposing ergonomic tools while getting out of your way as much as possible, so you can make Terrace your own.
+
+  Button primary
+    class inline-block mt-8
+    See Examples
+
+Section light
+  Heading 2 Core
+
+  Block
+    class flex flex-col space-between gap-16 md:flex-row lg:gap-48
+
+    Block
+      Heading 3 Tiny - <strong>Really Tiny</strong>
+        class mb-4
+      Markdown
+        The C version of the core parser is ~30 lines. Most other implementations are of comparable size.
+
+      Heading 3 Easy to Implement
+        class mb-4 mt-16
+      Markdown
+        Need to use Terrace in another runtime? The tiny core and reliance on rudimentary control structures makes that a cinch!
+
+    Block
+      Heading 3 Zero Dependencies
+        class mb-4
+      Markdown
+        All Terrace implementations rely only on the built-ins of their language. The header-only C core has no dependencies, not even libc.
+
+      Heading 3 No Dynamic Memory
+        class mb-4 mt-16
+      Markdown
+        Terrace allocates no dynamic memory of its own, working entirely on the stack. A great fit for resource-constrained environments.
+
+    Block
+      Heading 3 Unopinionated
+        class mb-4
+      Markdown
+        Terrace makes as few assumptions as possible about how you intend to use it, leaving you with the tools you need to use it as you see fit.
+
+      Heading 3 Available in 3+ languages
+        class mb-4 mt-16
+      Markdown
+        At launch, Terrace has a reference C implementation, a TypeScript/JavaScript implementation, and a Python version available as well. We’ll be adding more as time permits!
+
+  Button primary
+    class inline-block mt-8
+    Add a Language
+
+Section dark
+  Heading 2 Learn More
+
+  Block
+    class flex flex-col space-between gap-16 md:flex-row lg:gap-48
+
+    Block
+      class max-w-prose
+      Block
+        class flex gap-4 items-center mb-4
+        Icon info
+        Heading 3 About
+          href /about/
+          class mb-0
+      Markdown
+        Why does Terrace exist? What is it based on? What are the development goals?
+
+    Block
+      class max-w-prose
+      Block
+        class flex gap-4 items-center mb-4
+        Icon file-text
+        Heading 3 Documentation
+          href /docs/javascript/
+          class mb-0
+      Markdown
+        Setup instructions, API documentation, and recipes for how to perform common tasks with Terrace.
+
+    Block
+      class max-w-prose
+      Block
+        class flex gap-4 items-center mb-4
+        Icon users
+        Heading 3 Contribute
+          class mb-0
+      Markdown
+        Join the community! Help out by answering issues, expanding documentation, or building additional language implementations!
+
+  Footer