Subscript - Content Publishing using Web Technologies

NOTE

• ^[2020/12/16] This is a fresh git tree. There was too much binary data in the original git tree, and for other related reasons, I’ve decided to start with a new git repo for my Subscript project. The old subscript git tree can be found here github.com/colbyn/subscript.
• ^[2019] originally Subscript referred to a frontend UI framework, but that has been abandoned, I’m recycling the old Subscript name for a new project. The old project can be found here colbyn/subscript-old.

Preview

General Features

• Rust Macros
• Macros VIA a simple embedded scripting language that supports WebAssembly (Example)
• Unicode Prettification (E.g. convert "Lorem" to “lorem” and ... to …)
• Macros VIA some more mainstream embedded scripting language (ideally one that is sandboxed such as Deno)
• Paged Media Support
• PDF Rendering (dependent on Paged Media Support for native page handling)

Supported Content (Using Subscript's Macro System | Not Comprehensive)

• Include Files:

  <include src="../template/base.html">
      <h1>My Book</h1>
      
      <include src="../content/chapter1.html"></include>
      <include src="../content/chapter2.html"></include>
      <include src="../content/chapter3.html"></include>
  
      <!--
        NOTE: SEE HTML SYNTAX HIGHLIGHTING EXTENSION FOR VS-CODE
           (MAKES MIXING LATEX/HTML MORE BEARABLE)
        -->
      <h2>Graph of <tex>y = x^2</tex></h2>
      <desmos>
          <expr>y = x^2</expr>
      </desmos>
  </include>

• Graphing (still being moved over from the original implementation of the Desmos macro, unless you use e.g. this plugin (not as customizable).):

  <desmos>
      <expr>y = x^2</expr>
  </desmos>

• Mathematics:

  <!--
    NOTE: SEE HTML SYNTAX HIGHLIGHTING EXTENSION FOR VS-CODE
        (MAKES MIXING LATEX/HTML MORE BEARABLE)
  -->
  <equation>
      f \triangleleft x &= f(x) \\
      x \triangleright f &= f(x) \\
      |x| &= \sqrt{x^2} \neq x \\
      |x|^2 &= x^2
  </equation>

• Lots of simple conveniences (a lot is still being moved over from the original implementation):

  • Layout (originally called <gallery>):

    <layout columns="3">
      <equation>\delta \sin(x) &= \cos(x)</equation>
      <equation>\delta \cos(x) &= -\sin(x)</equation>
      <equation>\delta \tan(x) &= \sec^2(x)</equation>
      <equation>\delta \csc(x) &= -\cot(x)\csc(x)</equation>
      <equation>\delta \sec(x) &= \tan(x)\sec(x)</equation>
      <equation>\delta \cot(x) &= -\csc^2(x)</equation>
    </layout>

  • This helps reduce nesting:

    <list>
      <p>Lemon drops sweet roll cupcake biscuit cookie. Ice cream pie apple pie fruitcake dessert sweet roll chocolate bar.</p>
      <p>Sesame snaps lollipop marshmallow marzipan</p>
    </list>

  • Generate a “Table Of Contents” at the given location:

    <toc></toc>

    Regarding the <toc> macro, this also works with <include>'d content, thanks to how Subscript processes macros in a bottom-up manner^{(unlike PostHTML + Parcel, which drove me crazy)}.
  • Ad-hoc styling | This targets the parent node with a unique CSS class name:

    <style self>
        self {
            display: grid;
            /* ... */
        }
        @media (max-width: 900px) {
            self {
                grid-template-columns: 1fr;
            }
        }
    </style>

  • Images from a file glob [TODO]:

    <asset-glob src="../static/images/chapter1/*.png">
        <layout columns="2"><content></content></layout>
    </asset-glob>

    This pattern was very common with my old school notes, where I could include screenshots of all the essential definitions from a given chapter.

Versatility in Subscript is made possible VIA macros, the syntax is akin to web components, but it's expanded out at compile time, instead of at runtime (i.e. a macro).

What is Subscript?

• If you are a web developer:

  • Subscript is a akin web application bundlers such as Parcel, but is -better suited- for mostly static content publishing. For those who say otherwise, see my old GitHub repository (colbyn/school-notes), using Parcel resulted in significant friction from a multitude of problems, notably being that Parcel and PostHTML do not interact very well, especially with nested <include> resources and relative file paths.
    • For example, module A and B both include module C, where module C includes asset D. PostHTML processes <include> files in a top-down manner, so therefore, after inlining module C in A and B -A and B now reference module asset D, using a file path relative to module C... You can imagine Parcel would then throw errors at this... Subscript by contract mostly works in a bottom-up manner, where module C is processed first, then modules A and B.

• If you are from academia:

  • Subscript is akin to LaTeX, both are markup languages for displaying content.

    Furthermore both are geard towards STEM based content by default (unlike the Sile typesetter^† that doen't support e.g. mathematical notation).

    Yet Subscript is based on web technologies, and therefore can leverage the colossus ecosystem that makes up the web. For instance, need to display a graph of y=x^2? Just use a macro that embeds Desmos, and therein simply write:

    <desmos height="200px">
        <expr>y=x^2</expr>
    </desmos>

    Or, do you need to embed musical notation? Create a macro that embeds VexFlow.

    ^[†]: Regarding Sile and it's innovative layout system, since Subscript is based on web technologies, it can offer responsive grid layouts for different PDF resolutions.

Implemented Macros

See original implementation of macros.rs for macros that still need to be moved over.

Macro Name	Description	Example
<include>		<include src="../base/template.html"><p>Embedded Contents</p></include>
<page-nav>	Site Navigation
<layout>	Simple Layout Helper
<asset-glob>		<asset-glob src="../images/*.jpg"><content></content></asset-glob>
<markdown>		<markdown src="../posts/article1.md"></markdown>
<toc>	Generates a Table of Contents
<tex>	Inline LaTeX Math	<tex>y = x^2</tex>
<texblock>	LaTeX Math Block	<texblock>y = x^2</texblock>
<equation>	LaTeX Math Block In a nested equation and split environment	<equation>A &= B \\B &= A</equation>

High Level TODO:

• CSS Paged Media: support traditional print use cases, or just rendering to a PDF. This is what I am currently planning on using for rendering to e.g. PDFs: PagedJS

Math Preview

Comes with a syntax highlighting extension for VS Code.

It injects the LaTeX grammar from latex-workshop into the <tex>, <texblock> and the <equation> html tags.