This Site

This website is currently a Pull Request: #12127 ↗

If it isn’t merged, it will continue to be maintained at the current URL.

First, clone the repository which is a fork of helix:

git clone git@github.com:NikitaRevenco/helix.git

The actual website is located at the new-website branch.

git checkout new-website

Website is located within the website directory.

cd helix/website

Install the dependencies:

pnpm install

Note

I personally use pnpm instead of npm because it is more disk space efficient, but you can use what you want

• Start the development server:

  pnpm dev

• Create static output (html, css and js files):

  pnpm build

• Create build static output and preview:

  pnpm preview

Framework

This site is built using Starlight ↗, which is built upon Astro ↗ framework which is considered by many to be the best static site generation framework.

It also uses the following starlight plugins:

plugin	description
starlight-links-validator ↗	Ensures all internal links are valid before building site
starlight-blog ↗	Makes it easy to have a news section for new helix updates
starlight-image-zoom ↗	More accessible images for mobile users

Folder Structure

All the documentation is stored under src/content/docs, news are under src/content/docs/news.

Configuration for the sidebar including where each page is at astro.config.mjs.

• astro.config.mjs configuration for Astro and Starlight, including links on the sidebar
• tsconfig.json configuration for TypeScript
• package.json list of dependencies and scripts
• Directorypublic/ static files, mostly .asciinema .cast files

  • Directoryblog/ specifically for “News” section

    • …
• Directoryscripts/

  • termshots.js creates files in each directory under @/termshots that re-export every termshot
• Directorysrc/ main entry point for app, can be referenced absolutely with ”@”

  • globals.css
  • Directorytermshots/ contains termshot components

    • …
  • Directorycomponents/

    • Asciinema.astro renders terminal videos
    • Master.astro labels a section in the site as only available if built from source
    • …
  • Directorycontent/

    • config.ts
    • Directorydocs/ Docs are located here, each sub-directory contains .mdx files which represent a single page

      • index.mdx landing page for the site
      • Directorystart-here/

        • …
      • Directoryusage/

        • …
      • Directoryconfiguration/

        • …
      • Directorynews/ Specifically the “News” section of the site

        • …
      • Directoryreference/

        • …
      • …

Termshot

Some pages on this site use Termshot which is like screenshot + terminal = Termshot:

    1  fn main()               
    2    let numbers =          
    3      vec![1, 2, 3, 4];    
    4    let doubled: Vec<i32>  
    5      = numbers            
    6          .iter()          
    7          .map(|n| n * 2)  
    8          .collect();      
    9    // [2, 4, 6, 8]        
   10    dbg!(doubled);         
   11                          
 NOR   main.rs [+]   1 sel  3:1 
                                

Since terminals are rendered in characters, it’s possible to read these characters and convert to HTML which can be displayed, without the need of using images.

This is similar to what Asciinema ↗ does, except Termshots are just static pictures and not videos.

If you are creating a termshot for a .mdx file that’s called this-side.mdx, you would create a new directory in src/termshots/.

Create termshots

To actually create the termshot, the easiest way is to use Gnome terminal for that. (gnome desktop not needed):

1. Install dbus and gnome-terminal.

2. Open the terminal, for example with a 32 pixel wide by 20 pixel tall terminal:

   dbus-launch gnome-terminal --geometry=32x20

3. Put your terminal into the state that you want

4. Click on Edit in the top right corner and then Select All, this will highlight every cell in the terminal

5. Click on Edit again and then Copy as HTML, which transforms the terminal’s ansi escape codes into HTML that can easily be displayed. on a website.

6. Create a folder with the same name as the markdown document that you are editing. For example, this document is called this-site.mdx. If I were creating a termshot for it, I would create the following file:

   • Directorysrc

     • Directorytermshots/

       • Directorythis-site/

         • …

7. Create a file in PascalCase with a .astro file extension with a name of your choosing, and copy that HTML markup into this file:

   • Directorysrc

     • Directorytermshots/

       • Directorythis-site/

         • YourRecording.astro

8. To use it, import all recordings under src/termshots/this-site/index.astro (which will be automatically generated) as follows in a .mdx document, and then use it:

   this-site.mdx

   import { T } from "@/termshots/this-site/index.astro";
   
   <T.YourRecording />;

9. If the index.astro file doesn’t automatically appear (it will appear when you run pnpm dev for example), then create it with this command:

   pnpm termshots

Of course there are other ways, but this is the simplest one that I’ve found.

Note

On mobile devices, any termshot that uses more than 32 horizontal cells will have a scrollbar added, which negatively impacts user experience.

Asciinema

Asciinema ↗ allows you to create videos from terminal sequences and render them as HTML. It’s like termshot, but it allows playback and is a full-featured video:

Create asciinema videos

1. To create Asciinema videos, follow their instructions for creating a .cast file ↗.

2. Place the .cast file into the /public folder:

   • Directorypublic

     • my-video.cast

3. Use the Asciinema component, the contents from the /public folder are served at the root domain:

   import Asciinema from "@/components/Asciinema.astro";
   
   <Asciinema src="/my-video.cast" />

Note

When creating Asciinema videos or Termshot pictures, use :theme default to better reflect Helix’s branding