Static sites

Static sites are used in two context at Nasqueron:

1. Information static sites. Sites with only static content
2. JavaScript front-end clients. Sites with dynamic back-end: the HTML site uses JS to communicate with the back-end through a REST API.

Static site template

Static sites are composed from HTML, CSS and JS assets. They can be pure static sites, or clients for dynamic sites with JavaScript code to query an API, like infra-www.

We build the first sites from the Foundation CSS framework ZURB template.

This approach works well for pure static sites, or for JS clients to query an API like we do in infra-www.

Your site is composed of two parts:

• a src/ folder with your site assets (JS, CSS), pages and data
• a build mechanism driven by Gulp

This is perfect to quickly assemble a site, especially as we can do it on Jenkins for CD.

If you use frameworks like React/Vue and want to make them manage your site routing and structure, don't use this template.

Build mechanism

Currently, the build mechanism and the template are to be extracted from two different places:

  +-----------------+       +-------------------------------------+
  | Build mechanism |       | Site assets: SCSS, JS, HTML, data.  |
  |                 |       |                                     |
  | [ Gulp ]        |       | [ Foundation + Handlebars ]         |
  +-----------------+       +-------------------------------------+
          ^                                     ^
  +-----------------+       +-------------------------------------+
  | Copy it from an |       | Take the up-to-date last version    |
  | existing site:  |       | from the Foundation Zurb template:  |
  | infra-www repo  |       | foundation/foundation-zurb-template |
  +-----------------+       +-------------------------------------+

Create a static site manually

Step 1. To get the build mechanism right, as of 2023-05-28, take it from the join or from the infra-www repository:

   git clone https://devcentral.nasqueron.org/source/infra-www.git your-awesome-site
   cd your-awesome-site
   rm -rf src/ .git Jenkinsfile

You'll then get a folder with a correct build mechanism.

Step 2. Initialize your own repository:

   git init .
   $EDITOR .babelrc .browserslistrc config.yml gulpfile.babel.js package.json readme.md
   git add .
   git commit -m "Build a new static site"

At that stage, you've a correct build mechanism, configured for your website, but no template or content.

Step 3. Add the Foundation template:

Copy a fresh src/ folder from the foundation/foundation-zurb-template repository:

   git clone https://github.com/foundation/foundation-zurb-template /tmp/template
   mv /tmp/template/src .
   rm -rf /tmp/template

And that's it. You can now work on it and build your site.

You should get the following structure:

.
├── config.yml
├── gulpfile.babel.js
├── Jenkinsfile
├── package.json
├── readme.md
└── src
    ├── assets
    │   ├── img
    │   ├── js
    │   │   ├── app.js
    │   │   └── lib
    │   │       └── foundation-explicit-pieces.js
    │   └── scss
    │       ├── _settings.scss
    │       ├── app.scss
    │       ├── components
    │       └── global
    │           └── _typography.scss
    ├── data
    ├── layouts
    │   └── default.html
    ├── pages
    │   └── index.html
    ├── partials
    └── styleguide
        ├── index.md
        └── template.html

14 directories, 14 files

Enjoy. Follow your README instructions to install Node dependencies and build your site:

   yarn install
   yarn start

Who to contact for support. Dereckson maintains those instructions and this build mechanism.

Note about Jenkins. We're currently looking how to switch from the old Jenkins deployment method to the new Alkane one, so don't commit a Jenkinsfile (excepted if you solve that exact problem of course), we'll figure it as soon as your site is ready to be published.

Upsection

We need to maintain dependencies for the Gulp/handlebars site builder across several repositories. The dependencies are brittle, security issues will require to upgrade to a version of a package invoked by gulp-<feature>, but gulp-<feature> will be abandoned and unmaintained. That's the usual scenario. When it's maintained, the way to load the library in JS has changed.

That hard maintenance problem requires an unified solution, to be able to do it one for all the sites. Upsection is the name of this ongoing effort to maintain, and provide a tool to populate the dependencies and build the site with a simple `make`. Proof of concept lives in upsection.

A second advantage is the current repository creation process is a little bit cumbersome, as highlighted by the previous sections instructions to fetch the build mechanism and the src/ folder in two different sources.

Upsection repository contains our full usable template in ONE place.

As of 2024-10, Upsection dependencies aren't up-to-date, so you'll need if you use it to upgrade Node packages to the one used in join or infra-www.

Expected features:

• Create a site with a `upsection` command
• Being able to only store upsection configuration + assets directories in the websites repositories
  • `upsection` can regenerate the build mechanism: package.json, node dependencies
  • Site get freshest dependencies for the build mechanism

Current languages stack:

• At upsection level
  • Python for upsection itself
  • BSD make (Makefile) to generate needed files
• At static site build level
  • Node.JS and Gulp still manage the site build
• For the site assets
  • SCSS
  • modern JS with Babel to transpile when needed
  • HTML from handlebars templates
  • YAML for data

Build Vue.js application

Nidal uses another strategy for servpulse: Vue.js provides a CLI tool to bootstrap a web site, and Foundation is added afterwards:

npm init vue@latest

Who to contact for support. Inidal maintains those instructions and this build mechanism.