indexnotes

First time web dev

My first touch with actual web development has been the development of this site using Astro. Previously, I used Hugo to generate the predecessor to the current site’s design—but I don’t consider that “real” web development since much of the logic and hard work has already been done for me (by the static site generator).

Overall, it has been quite pleasant, relative to how large of a meal Astro + Node + HTML + CSS + routing + deployment + more is.

HTML tag semantics §

  • HTML tag semantics matter. Don’t be confused by the fact that, by default, tags have styling. How a page looks should be controlled by CSS.
    • Don’t confuse the default look of elements for their role in the document
    • It is intuitive to use <i>, <b>, <br>, <em>, and so on for basic styling. However, HTML tags should convey the meaning of text, not what it looks like.
    • In practice, this means these tags should be used pretty much only in prose, not in UI elements like the footer, navbar, site header, and so on.
  • HTML semantics also matter for contexts in which your HTML is presented outside of your pages. For example, reader modes (e.g., Firefox’s Reader View), or RSS feeds: these are contexts in which the styling of your text is inferred from your HTML tags and attributes, not your stylesheets.
  • Semantics for a few key or rare (but useful) tags:
    <body>

    The “actual” (displayed, rendered) content of the page.

    <main>

    Dominant content of the page. Typically includes everything but the site footer and header. Only one per page.

    <article>

    Represents a self-contained piece of composition. Can be used multiple times a page. For example, a blog post or each card in an article listing.

    <header>

    Introductory content (to site, to article, etc.). Can be used multiple times a page.

    <nav>

    Provides navigational links.

    <footer>

    Closing and supplementary information (e.g., author email address, copyright license, related links) about a given section (e.g., article). Can be used multiple times on a page.

    <section>

    Delimit thematic grouping of elements in a page. Most of the time, these involves a heading element.

    <time>

    Represent a period or point in time. Useful to search engines and other site features that use machine-readable time formats.

Accessibility §

  • Don’t forget about it! Consider theme contrast, non-sighted users, and user preferences like preferences for high-contrast (prefers-contrast) or no motions (prefers-reduced-motion).
  • Know ARIA standards and attributes, like aria-label, aria-labelledby, aria-pressed, and WCAG recommendations.
  • There are conventions for accessible use of heading tags. How-to: Accessible heading structure - The A11Y Project explains, alongside sharing a few browser add-ons to help.

Select one or two fonts §

  • Fewer is better; aim for simplicity and elegance. Almost all sites should only really need 2 fonts. Currently, this site has a main “for prose” font (serif) and a secondary font (sans serif) for various other places, e.g. UI elements and heading text.
  • Real life examples: Fonts In Use - Fonts In Use, phenomenal source to see what fonts people have used with each other
  • Font providers

Fluid/responsive typography and spacing §

There’s MD, MDX, and Markdoc §

  • I had to make a decision on what file format my content should be in.
  • I chose MDX, since I think it is as expressive as possible. (I export from Org-mode to MDX and don’t think there’s any HTML I want to emit that I can’t have my backend export into MDX.)
    • Exporting to MDX makes for an easier time than exporting directly to HTML since MDX takes advantage of Astro components as well as opens the possibility of inserting Remark integrations to further customize the emitted HTML (although ideally that customization should be done by modifying my Ox-mdx exporter). I’d rather tidy up and standardize the final HTML output through Astro and its integrations, not Org-mode exporter stage.
  • But Markdoc was an enticing, albeit less common and support (by third-party packages), option. See Markdoc | Frequently asked questions and Markdoc | The Markdoc syntax.

Generators and aggregators §

Astro components are awesome §

  • They’re great. “Beginner friendly, simple, and powerful yet a thin abstraction” is my impression.
  • CSS selectors get scoped (but not rules, which are rendered normally).
  • Makes putting related things (e.g., CSS rules, HTML, JS) near one another.

Favicons §

  • Favicons and SVGs

  • Don’t forget to have a favicon for each of your site’s color themes. You can have a different SVG for each theme, or have a style block in a single SVG which uses CSS media queries to change the colors of the SVG dynamically. For example, this site currently uses something like:

    <!-- Adaptive-color favicon, depending on `prefers-color-scheme` -->
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="...">
      <style>
        .icon-fill {
            fill: #1a1a1a;
        }
    

        @media (prefers-color-scheme: dark) {
            .icon-fill {
                fill: #ffffff;
            }
        }
      </style>
      <path class="icon-fill" ... />
      <path class="icon-fill" ... />
      <path class="icon-fill" ... />
    </svg>
tagged
AstroWeb developmentSite design