Stac Website

This is the repo for stacspec.org.

The website is built using the Node.js based static site generator 11ty.

Tutorials are created using markdown and jupyter notebooks, and the page templates are written with Nunjucks.

Getting Started

Prereqs

• Node & NPM
  • Recommended mac installation with homebrew & nvm
  • Recommended pc installation with chocolatey & nvm
  • nvm documentation
• Docker (If adding Jupyter Notebooks)

Installation

npm install
npm run serve

If this step results in errors, I recommend using node version 17.8.0, the current stable version at the time of writing.

Creating Tutorials

New tutorials are created in markdown format and added in to the [app/tutorials] directory.

Tutorials are categorized by adding them to a directory in the tutorials folder.

Tutorials should be in their own directory along with any translated versions of the tutorial.

Heres an example:

app/
    tutorials/                           # this is the tutorials root
        getting-started/                 # this is the category
            stac-collections/            # this is the tutorial
                stac-collections.en.md   # this is an english version
                stac-colecciones.es.md   # this is a spanish version

The url paths are autogenerated, for the tutorials shown above they would be:

/en/tutorials/stac-collections
/es/tutorials/stac-collecciones

Tutorial Frontmatter Requirements

You'll need to add a few properties in yml format to the markdown frontmatter at the very top of your file. Here's an example:

---
title: A title for your tutorial, this is used for SEO and in previews throughout the site
description: A short description of the tutorial. This will be used in the meta description and in tutorial previews throughout the site.
notebooks:
    - name-of-notebook-file-no-extension
---

the notebooks property is optional, and will add a notebook from the notebooks/build directory below any markdown content you add to the tutorial.

Compiling Notebooks

Add notebooks to the notebooks/src directory

Notebooks can be built via python 3.9 with the included docker-compose config by running:

docker-compose up

Docker is the more consistent way to compile the notebooks, but you may also run the bash build script directly if you have python 3.x installed on your machine:

cd notebooks
pip3 install -r requirements.txt
sh build_notebooks

Creating Pages

If you want to create a new page, here are the steps you'll follow

1. Create a .html file for your page template in the app/pages directory.
2. Create a content file in the content directory, and be sure to require that file in the parent content file (for a new "about" page, include it at the bottom of the content/about/index.js file. For a new base level page, you'd include it in the content/index.js file.
3. Link the template file with the content file by adding a name to the template frontmatter (see Page Frontmatter Requirements below)
4. Add a route to the page for each translation (Also see Page Frontmatter Requirements below)
5. Now you're ready to create your page, you can use the content you add to the content files with the localize filter, i.e. {{ .hero.cta_text | localize }}. Review the Page Content section below for more detail
6. Pages are written using the Nunjucks templating language, review the Nunjucks documentation to see all the options available to you

Page Frontmatter Requirements

You'll need to add a few properties in yml format to the markdown frontmatter at the very top of your file. Here's an example:

---
route:
    en: /en/example-url-for/english-translation
    es: /es/url-ejemplo-para/traduccion-en-espanol
name: example.correlates.toAContentFile
---

The route property creates the URL for each translated site.

Page Content

All page content is added to the content directory.

The page name property should correlate to the content path. For example name: about.stacSpec correlates to the content/about/stac-spec.js file. This works because the file is exported from the file and imported into the content/about/index.js file, which is then imported into the larger content object at content/index.js.

To reference the content from the correlated content file in the template files, you can use the filter localize, like so:

{{ .hero.cta_text | localize }}

with the first . in .hero referencing that the content should be scoped to that correlated file, rather than the content root.

All content is saved in a format that the Eleventy i18n plugin recommends. The final property in the tree should correlate to a locale code, for example:

hero: {
    cta_text: {
        'en': 'Click',
        'es': 'Hacer clic'
    }
}

If in the future, it becomes too cumbersome to manage content in the filesystem, eleventy can generate content from API calls as well. An example of this can be found in app/_data/catalogs.js

Translations

If you want to translate the site into another language, here are all the steps you'll need to take:

1. Translate all content

In the content files (everything in the content folder), anywhere you see an en: means it is the english version. Add your translation with the locale code right next to that, i.e:

hero: {
    cta_text: {
        'en': 'Click',
        'es': 'Hacer clic'
    }
}

2. Add translated urls

in each template file (anything in pages folder), add your translated route to the routes config. I.e:

---
route:
    en: /en/example-url-for/english-translation
    es: /es/url-ejemplo-para/traduccion-en-espanol
---

3. Translate tutorials

In the tutorials folder, anything with the extension en.md is a tutorial in english. Copy this file in the same folder and add the locale in place of en. You can also translate the filename to give the tutorial a translated url for example hello.en.md would be copied as hola.es.md in the same folder. The url for that would be stacspec.org/es/tutorials/hola.

4. Activate your translated site

In the file app/_data/locales.js, add your locale to the list. Right now the entire contents of that file are:

module.exports = ['en'];

To add spanish, you would update that to be:

module.exports = ['en', 'es'];

Deployment & CI

The site deploys automatically from the master branch using Netlify.

When opening a pull request, Netlify will generate a preview environment.

Architecture

• Node.js is the base technology that the site is built on
• Site uses the 11ty static site generator to compile all the site files into a static website build.
• Templating is in the Nunjucks templating language
• Docker is used to build notebooks
• Tailwind CSS is used to reduce the amount of custom css without compromising custom look and feel
• Alpine JS is used to create interactive components

Data

Most of the site data is pulled into the 11ty data cascade and available in template files, either as collections (i.e. app/tutorials) or as global data (i.e. app/_data/catalogs.js.

These are the data types in brief, with links to readme locations where more info is available:

• pages: Created by 11ty based on the files in app/pages
• tutorials: Added to app/tutorials directory as markdown files
• categories: Autogenerated by tutorial directory structure
• routes: Created from route frontmatter in the page template files
• content: One big javascript object, passed into global data and accessible via the localize filter

Images

Images are compressed and resized using the Eleventy Image plugin.

You can add an image to the assets/images direcory, and include it in your template files via the image shortcode with a filename, alt text and size. For example:

{% image 'assets/images/STAC-01.png', 'stac logo', '300px' %}

You can also add different sizes for different breakpoints by updating the last parameter, like so:

{% image 'assets/images/STAC-01.png', 'stac logo', '(min-width: 1000px) 800px, 400px' %}