Development Tutorial

A quick reference of what to do (with respect to the frontend stuff), with links to relevant documentation:

Quick Start

I originally used 11st-starter-kit. We have to deviate from it a bit (due to its use of an old 11ty version, and it took me a while to fix some of the remaining issues because of the dependency mess of the JavaScript ecosystem), but you can play with it as a quick primer for our stack: 11ty with WebC, Alpine.js, and TailwindCSS.

WebC (which is what 11ty recommends now) stands for "web components." This is probably why it seems familiar to React developers. See here for 11ty's documentation, but do note that it doesn't discuss many edge cases and, in some situations, you will need to do some research in their GitHub issues (they do have bugs that they have not fixed!). When in doubt, feel free to shout in their Discord as well.

Warning

You should not use any other templating language in this implementation, other than WebC, Markdown and HTML. Unexpected behaviour could happen (most notably, it might reinterpret what you wrote as WebC again)!

Directory structure

• The _data folder is for global data files. In the (near!) future, JavaScript data files would be needed to deal with the document database (for tags and page content, the latter being already in the dynamic branch).
• The _includes folder is for dependencies for building pages. It has two subfolders:
  • The components folder includes, well, components. Each component resembles HTML components, as intended. As defined here, every webc file defined here are available to other pages as components, so if you have example.webc there, then you can use <example></example> elsewhere. See here.
  • The layouts folder includes, well, layouts. Each page can inherit another layout by defining it in the front matter. Similarly, each layout can also inherit another layout. The inheritance is done through the "content" variable.
• lib is for script dependencies. Currently there are dependencies for the Parsons problem and the syntax highlighting components for code. You should not need to touch it.
• styles is for stylesheets. By the way, you can use stylesheets in components as well, and they will be bundled in the output.
• main.js initializes Alpine.js; parsons.js is the main script for the Parsons problem.
• The two Markdown files are, well, pages.

Database-driven pagination

page.webc shows what is needed for generating pages based on database content. I referred to this tutorial.

Currently what it does is that for each field (search for webc:for), given the type of each field (eg. webc:if="f.type == 'text'"), render an element. We'll abandon this template eventually, but you can see how basic webc logic is used here.

Client-side scripting

We use Alpine.js. Their documentation is simple and without gimmicks, so give it a good read. Any component property that is prefixed with x- has interactivity handled by it.

Warning

You cannot use shorthand : and @ for properties, they conflict with WebC! You must use the x--prefixed property name in full!

Notable places where Alpine.js used here are:

• The homepage filter (see here for handling the selected filters, and here for determining what should and should not show)
• Arduino/Trinket split handling (see here for the switch, here for storing the value of the switch, and here for reading the value of the switch)

CSS

We use TailwindCSS. Knock yourself out with those class names... (Don't you hate how many class names they'd put on one element now?)

Tasks

What needs to be done, in order, is:

1. While inheriting _layouts/base.webc, build the layouts with purely HTML components, according to Figma specifications. For this step you only need to fill in the components with sample properties, but remember to document what logic, if any, is required for each component! You can create a dummy page that inherits the layout to test it.
2. Determine what the variables are in each layout, then structure the database so that it supplies those variables. (The database already exists, but it may be necessary to continuously improve it.)
3. Add WebC and Alpine.js logic into the layouts. (If basic if-else-for is not enough, a render function would be helpful.)
4. Modify page.webc so that it applies the correct layout and variables to each page in the database. Computed Data will be very useful here.