Yax.com Daily Worklog
August was more pain than joy in the development of Yax.com. Wanting to push forward, I found myself blocked by several technical issues that I couldn’t resolve on my own. Still, there was progress. By mid-August, I’d completed a try.yax.com site that provides a demonstration of how a visitor can build a website with Yax.com. There’s only a single demonstration template and I’d like to add more templates soon but for now I’ve focused on writing the first few tutorials that will help both people building websites and developers building templates.
In September I hope to surmount the technical issues that are holding me back and begin to build a gallery of website templates.
August 1, 2020
For Yax, I currently have:
- yax.com (a landing page)
- tutorials.yax.com (web components and Markdown files)
- blog.yax.com (a Hugo site)
Today I deployed assets.yax.com, a website that serves web components to the other sites. A navigation bar and footer are now sourced from assets.yax.com, providing consistency across the three sites from a single source.
Two months ago, the yax.com website was just a landing page and a blog, generated by the Hugo static site generator. Hugo seemed the best platform at that time because I just wanted to generate a blog from Markdown files. But Hugo is complex. It required 153 files to generate a five page website (configuration files and themes and layouts and partials and pages for categories and tags, and so on). There’s no need to use Hugo to generate a simple landing page for the main yax.com site. So I split off the main site and moved the blog to a separate subdomain blog.yax.com which is hosted on Netlify from a separate GitHub repo. For the blog, I replaced some complex Hugo “partials” with my own navbar and footer custom tags served from the assets.yax.com website. For me, web components can reduce the complexity of the Hugo static site generator.
August 2, 2020
Today I worked on the publishing system for the tutorials website. I’m “using the platform” (what’s built into the browser) so I won’t need a static site generator (like Hugo) or a framework (like React or Rails) to publish tutorials. The main ingredient is a custom element that reads a Markdown file and renders the content (including syntax highlighting for code examples) on a web page. I started with the prism-markdown-element created by German Martinez Solis and tweaked it to automatically look for a Markdown file that has the same name as the HTML file. This way, a tutorial can have multiple pages based on multiple HTML files. Every HTML file is identical except for its filename. So it’s easy to replicate all the pages needed for a tutorial just by creating look-alike HTML files and naming the files index.html, 1.html, 2.html, and so on, with Markdown files named index.md, 1.md, 2.md, and so on for the content. The other key ingredients are custom elements for the navigation that are specific to a tutorial layout:
- header for a title
- table of contents
- navigation breadcrumbs
- previous/next pagination
For the tutorials, a manifest file provides the information needed for the title and navigation. Static site generators like Hugo often require “front matter” in their Markdown files. I like to keep the Markdown files “pure” and portable without the clutter of metadata. Today I got it all working nicely after fixing an off-by-one error in the paginate tag (“There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors.”—Jeff Atwood).
August 3, 2020
I’m glad I made some progress yesterday because I spent the entire day preparing documents for my Indonesian visa application and paying bills. The Internet was down at my rented office so I worked from my villa instead.
August 4, 2020
I worked on some articles for the tutorials site and I tweaked the landing page for the tutorials site to improve the messaging:
“After writing popular books and articles about building websites with complex frameworks for ten years, I’d like to introduce you to a quicker and easier way to build and publish websites, using nothing more than the technology that’s built into web browsers.”
August 5, 2020
I added an articles section to the tutorials site, as a place to add shorter “how-to” articles that aren’t full tutorials. The first article is Use a Git Submodule to Share an Assets Library which I extracted from the tutorial How to Build a Custom Tag Library after I decided it is better to deploy an assets website. Also, I found https://favicon.io/ (a website that generates favicons) and added favicons to the yax websites.
August 6, 2020
I rewrote the section “Sharing an Assets Library” for the tutorial How to Build a Custom Tag Library. I also wrote an article “How to Create a GitHub Account.” Creating a GitHub account is really basic but I want to explain everything for users starting at the very beginning.
August 7, 2020 and August 8, 2020
Overnight trip to the volcano Gunung Batur. Saw the sunrise and watched smoke rise from the caldera.
August 9, 2020
Wrote basic articles to support beginners:
I plan to write similar articles about Netlify and Render.com to support a choice of hosting platforms.
August 10, 2020
I created a new web component <yax-articles-list> that displays a list of articles on the tutorials landing page. It is populated from a manifest file.
August 11, 2020
I created a <yax-tutorial-crumbs> tag to display navigation breadcrumbs and a publication date for each article or tutorial. Now the tutorials.yax.com site is feature complete.
August 12, 2020
I’m starting to build a website for a step-by-step demonstration of how to build a website with Yax.com. I created a GitHub repo and deployed try-yax-com to Netlify as try.yax.com.
August 13, 2020
I found a component for a timeline in Bulma that’s easily adapted to show a series of steps in a vertical progression. Good for the step-by-step demo at try.yax.com.
August 14, 2020
I completed the try.yax.com site today. During testing, I found Safari doesn’t support JavaScript FormData events. It sucks that JavaScript is not consistent across browsers. I also fixed a problem with the DeployNow button on try.yax.com (for users with no GitHub email address). I tested and try.yax.com now works on Safari and Chrome with different GitHub accounts. It’s complete for now.
August 15, 2020
I deployed the api-yax-com repo to Vercel and set up a subdomain for api.yax.com. I had to deploy the repo from my personal account because Vercel requires a paid plan for deployment from organization accounts. I’ll set up an organization account after I’ve evaluated Vercel. So far it’s very simple to write a Ruby program in an api directory and deploy it as a serverless function.
I took a few minutes and looked at the GitHub permissions that are requested when a visitor builds a website with Yax. Developers often object (rightly so) if the scope of GitHub permissions are too broad. Initially I was requesting access to the user’s email address but I decided to narrow the scope of permissions and only request the bare minimum, which is read and write access to public repositories.
It’s now possible to: - visit the main Yax.com landing page - see a walk-through demo with Try Yax - read Yax tutorials to set up hosting and custom domains
August 16, 2020
I reviewed options for next steps. Which to do next?
- hire a designer to create a logo
- add open source details (license and code of conduct)
- add a database to record visitor use of Try Yax
- create a video for the Try Yax landing page
- rework the yax.com main site (add a CTA for Try Yax)
- study how to implement templating with custom elements
- build a gallery of templates
- write a tutorial about templating with custom elements
- write a tutorial about how to create templates for Yax
- polish tutorials and add missing screenshots
- add a payment gateway for tutorials subscription
I chose, “add a database to record visitor use of Try Yax.” I’m eager to start demonstrating Yax as a proof of concept and I want to be ready to track use as people begin to try it. I’d like display the usage stats on a new yax.com landing page as a way to encourage people to watch our progress. I’ll try the FaunaDB “cloud database” service as a backend to record Try Yax use.
August 17, 2020
I installed a faunadb-ruby gem and modified the api.yax.com deploy function to send usage data to FaunaDB. I tested and got errors. There is a version conflict introduced by the faunadb-ruby gem dependencies. There is an open pull request to fix it but it’s been a month and it hasn’t been merged.
It’s a just a simple HTTP request to send the data to FaunaDB so I decided maybe I don’t need a full driver, I can try to implement the HTTP request myself. I couldn’t find FaunaDB examples of pure HTTP API requests so I posted to the FaunaDB Discord forum. I got a quick reply:
“We do not have the wire protocol documented which makes writing a custom driver or building an application where queries are called via pure REST a risk. If you do want to dive in, the best approach is to inspect the drivers source code, looking at the serialization etc, it’s ‘developer friendly’ enough, but we can’t guarantee compatibility for future releases.”
August 18, 2020
As a starting point to reverse engineer the HTTP request to send data to FaunaDB, I created a simple JavaScript app with a submit button. I ran into errors importing the JavaScript FaunaDB driver but got quick help from jkrishna on the JSPM Discord forum. Then I made a dumb error and got quick help from Brecht De Rooms on the Fauna forums.
August 19, 2020
I got a JavaScript app working to write data to FaunaDB. I thought more about next steps to send data to FaunaDB from my Ruby function. Realized I could try to import the patched version of the faunadb-ruby gem directly from GitHub and it should be easier than trying to implement an HTTP request. Decided to look into this next. But I got sidetracked the next day.
August 20, 2020
All my LitElement-based custom elements failed overnight with no changes on my part. The navigation bar and footer failed on all the sites. And the custom elements on the tutorials.yax.com site all failed. Turns out there were new releases of lit-element (version 2.4.0) and lit-html (version 1.3.0) published 12 hours ago. I posted an issue on the LitElement GitHub repository and got help on the Polymer Slack channel from Thomas Allmer of Open-Wc. It turns out the failure was caused by my poor implementation of imports (I loaded lit-html twice) combined with some ignorance about how pinning versions works with JSPM.
August 21, 2020
I wrote an article Troubleshooting Lit-Html: Code Displaying in the Browser to help anyone who encounters the same issues with Lit-Html. Also created a question and answer on Stack Overflow.
August 22, 2020
I revised the article on Lit-Html code displaying in the browser with suggestions from Thomas Allmer. I also opened a LitElement issue, Re-export lit-html directives from LitElement, and got a quick response from Justin Fagnani, the lead developer on LitElement.
August 23, 2020
I improved the formatting for code in the articles and tutorials. Also returned a favor to Thomas Allmer by helping with some edits to a blog post at ModernWeb.dev, a new site that the Open-Wc collaborators are launching this week to support buildless web development in JavaScript.
August 24, 2020
Took a day to better understand how to manage dependency versioning in JavaScript.
August 25, 2020
Continued with some research into buildless web development in JavaScript.
August 26, 2020
Did some experiments to see if LitElement can be used within the HTML <head> element. I’d like to build a custom element that can output the boilerplate that is required in the <head> section of every web page. On the Polymer Slack channel, Serhii Kulykov, Benny Powers, and Mahdi Ridho helped me understand the problems I encountered and made some helpful suggestions.
August 27, 2020 and August 28, 2020
I returned to my project to send Try Yax usage data to FaunaDB, this time using a patched version of the faunadb-ruby gem. It works great locally but the gem fails to load when I deploy the function to Vercel. Spent two days trying to figure out how I can get Vercel to load the patched gem from GitHub.
August 29, 2020
No help yet from Vercel support on on the issue of loading a patched gem from GitHub so I decided to look at Render.com as an alternative to Vercel. I quickly got the patched faunadb-ruby gem working on Render.com. Good to get confirmation that it’s not a code issue, just a Vercel issue.
August 30, 2020
Great to see Render.com is a good option for hosting websites for Yax users. I wrote articles to make it easy to get started with Render.com:
August 31, 2020
I continued enabling Render.com as an option for Yax users by adding a “Deploy to Render Button” to the Yax demonstration template. I tried a Render.com deploy from try.yax.com and it worked nicely. I added Render.com as an option on the landing page copy for Try Yax.
Here’s the roadmap for my next steps:
- finish Try Yax by adding tracking with FaunaDB
- create a custom element to display Yax templates
- create a gallery for Yax templates
- build a collection of tiny site templates to populate the gallery
- write a tutorial about how to create Yax templates
- start talking to designers and developers about Yax
Previous: Worklog for July 2020 - Next: Worklog for September 2020