Skip to content

v3

Jump to bottom
Alex Hoyau edited this page Jun 7, 2023 · 39 revisions

Silex static website builder

I started a new documentation site for silex v3

To be documented

This doc is a work in progress as the V3 is being developped

Missing still in this doc

  • symbols allow you to define areas inside your webpages to indicate they are the same area, to be maintained "as one" throughout your entire website.
  • {{ site.url }}{{ site.baseurl }}
  • current
  • modernizr lib
  • env var LANGUAGES_COLLECTION
  • https://github.com/silexlabs/eleventy-plugin-directus/
  • set filter
  • get directus
  • pages and all collections
  • singleton filter which is equivalent to {% assign global = collections.all | where: "collection", "global" | where: "lang", current.lang | first %}
  • collections which are pages (same as all but they need to have a permalink + not draft on prod) collections.pages

pour qu'un page s'affiche

  1. elle doit avoir name ou title ou permalink (supporte le multilingue)
  2. dans silex il doit y avoir une page avec son nom
  3. dans directus il doit y avoir une collection avec son nom
  4. optional field layout

snipcart: SNIPCART_API_KEY, 2 includes process.env.DEFAULT_COLLECTION, process.env.LANGUAGES_COLLECTION, process.env.LANGUAGES_DEFAULT, process.env.LANGUAGES_DEFAULT_KEEP_IN_PATH

online/final url of an image: {% assign image =current.image | directus_asseturl %}{{ site.url }}{{ site.baseurl }}{{ image | optimizeImage }}

escape quotes: {{ current.texte | replace: '"', '"' }}

bug stastic ">" => ">"

hooks: hooks from 11ty service called by silex (hooks.js) params

Shortcodes:

  • onclick: {% onclick "alt text on the linkjk" %}SOME HTML HERE{% endonclick %}
  • template: use to generate a template for client side rendering {% template "template-name" %}HTML HERE WITH EJS templates for client side JS to use <%= test %>{% endtemplate %}

filter toLocalDate: {{ a_date | toLocalDate: "fr" }} which eleventy plugins are activated, .rich-text for https://www.npmjs.com/package/eleventy-plugin-typeset

Stack technique

Tools used to build Silex v3

Features included

  • No-code web design
  • No-code content type builder
  • End user friendly CMS
  • Deployment and hosting on github pages with a Github action or with Netlify
  • Deployment to any hosting company (FTP) with a Github action
  • Images optimization: webP, serve different sizes, including images uploaded by end user through directus
  • Slideshow with arbitrary HTML as slides
  • Basic structure for a site with a blog
  • Basic design ready to edit with Silex
  • See the road map for features to come

Installation

TBD

Here are the different versions available

  • Silex desktop app (Linux, MacOS, Windows)
  • Deploy Silex on heroku with 1 click install
  • NPM module
  • Docker compose

Getting started

Work online

You can work 100% online, without installing anything on your local computer. This is a good way to work on design, but developers will want to work on their local computer

TBD

  1. Open Silex editor in your browser or as a desktop app
  2. Create a website on Directus cloud
  3. Plug in your directus instance: add a secret in github with the name DIRECTUS_URL set to your directus root URL, e.g. https://l7ch6l.directus.app and restart the repository action
  4. Create a page: new page in directus

About modules

Modules are a way for the end user to use the CMS and add sections

Good to know:

  • in Silex/Stastic, all modules should be on the page Page (the layout used for pages)
  • each module is made of 1 or more sections

Modules themes

In case you want to have several different styles for all modules, e.g. dark/light backgrounds:

  1. in directus, create a field style for each module, with a way for the user to select one of the style, e.g. dark and light
  2. in Silex/Stastic, add to the module sections the CSS class {% module-css modules, forloop.index %}
  3. in Silex/Stastic, in the CSS editor, define the CSS classes, e.g. .dark and .light

This will let the user choose a CSS class which will style the module's sections

In case you want to have a module look like it is on top of the next module, e.g. effect used in this site, then you need to add to a section the style of the next module. Simply add this CSS class: {% next-module-css modules, forloop.index %}

Modules implementation in liquid

Before all the modules, add a section with these liquid templates:

  • Before: {% comment %}
  • After: {% endcomment %}{% for module in modules %}

After all the modules, add a section with these liquid templates:

  • Before: {% comment %}
  • After: {% endcomment %}{% endfor %}

Before each module, add a section with these liquid templates:

  • Before: {% assign moduleName = "module-text" %}{% comment %}
  • After: {% endcomment %}{% if module.template == moduleName %}

After each module, add a section with these liquid templates:

  • Before: {% comment %}
  • After: {% endcomment %}{% endif %}

About collections

Each collection in Directus is made available to 11ty templates (Silex pages)

To be documented

An item of a collection in Directus is rendered by 11ty as a page only if:

  • The collection is public (see "roles and permissions" menu in Directus settings)
  • The item has a field title or name or a translation with permalink in it
  • If the item has a field is_page set to false it will not be rendered
  • The collection name is also a layout, i.e. a page in Silex
  • The permalink of the item resolves as an HTML page

In case an item is not considered to be a page, it will be available in the global variable cms but it will not be in the global variable pages

11ty and liquid templates

We use 11ty with liquid templates in this repository. This means that can use liquid templates in your layouts, i.e. add liquid in the { } tab in Silex/Stastic:

liquid templates in silex/stastic

Bellow are details about the 11ty / liquid part of this starter. You can see examples in the file /.silex/example.html (to be opened in Silex / Stastic)

The content files which are already existing:

content file layout permalink description
content/pages/404.md default /404.html The page displayed for non existing pages. This is made the default page bu the file .htaccess or by the file permalink on netlify and github pages
content/{{ collection }}.md the same as collection, e.g. Page layout for the page collection defined in the file This is where the collections become pages and posts
content/category.md category This page display a paginated list of all the pages or posts of a given category. It is duplicated for each category found in the pages and posts.
content/sitemap.md none /sitemap.xml This page lists all the other pages in a format that search engines understand
content/robots.liquid none /robots.txt This page references the sitemap and disables SEO for the /admin/ folder which is used by forestry.
_data/global.json none none This file contains all the data which is global to the whole website, which not related to a page. You can access the data in liquid with {{ global.* }}

Here are the available collections by default as defined in Directus:

  • collections.page
  • collections.post
  • collections.languages

Here are the available includes:

  • collection: display a list of pages or posts of a given category. This will be useful for navigation and posts lists, see the comment here
  • pagination: to be documented, does it work?
  • categories: insert a list of page or posts filtered by category, see the comment here
  • nav: insert a list of links, see the comment here

Shortcodes

  • slideshow: create a slideshow out of a container, see the comment here
  • module-css and next-module-css: add CSS classes on modules sections, see the comment here
  • imgtag: returns a responsive image tag with {% imgtag src_attribute, alt_attribute, width_on_mobile, width_on_desktop %}
  • bgimgtag: returns a <style> tag with CSS code to create a responsive background image on an element with {% bgimgtag src_attribute, css_selector, width_on_mobile, width_on_desktop %} - this will create the css rules to apply an optimized bg image

Filters

  • translate: add the translated attribute in case it has not one already, for example when the item comes from the user selecting a page in the UI: {% assign targetPagePerma = item.page | translate: lang, 'page' | permalink: true, 'page' %}, see _layouts/nav.js for a real life example
  • permalink: the permalink of any collection item, e.g. {{ collections.page[0] | permalink }} returns /index.html and {{ collections.page[1] | permalink }} returns /name-or-title/index.html and {{ collections.post[0] | permalink }} returns /fr/post/name-or-title/index.html. The collection need to be translated (translate filter) and to have the attribute collection set or use the optional name param, check the code in scripts/utils.js
  • absolute: the absolute URL of a path, e.g. {{ '/test/' }} returns http://localhost:8080/test/, as per the site's url and baseurl properties (which comes from the env vars URL and BASE_URL)
  • alternate: get all alternate versions of this page, e.g. all other languages, e.g. {% assign alternates = current | alternates %}{{ alternates.en }} => /en/page-title-in-english/
  • asseturl: get the URL from an image object coming from directus collections, e.g. {% assign url = item.image | asseturl: 'This is a text displayed when an error occures (i.e. to find missing images)' %}
  • optimizeImage: get the final image URL from a local image URL, e.g. {{ site.url }}{{ site.baseurl }}{{ current.translated.share_image | asseturl: 'share image' | optimizeImage }} will return something like https://www.mysite.com/uploads/aacd7556-5b17-4c00-b35e-9a35bd9efc53.png

Client side libraries (in Silex / Stastic)

Directus

This repo contains a directus server for local development, see .directus's README.md

By default this server is used, but you can set the environment variables DIRECTUS_URL, DIRECTUS_PATH, DIRECTUS_PORT to change this default, as defined here.

Every collection you create in directus will be made available to Silex/Stastic layouts by eleventy as per this code, i.e in directus the collection pages has a name field which is available in the layouts as {% for item in collections.pages %}{{ item.name }}{% endfor %}

The 2 base collections created in this starter are pages and posts. Pages are rendered with this file. Posts are rendered with this file

Silex

In order to edit 11ty layouts, we use Stastic, a fork of Silex augmented with templates / layout editing features. In stastic you can use 11ty's builtin language "liquid" to create layouts.

Tip: look at the tabs "{ }" and "CMS" in the properties on the right liquid templates in silex/stastic

Start with the sample site /.silex/example.html, also called "the starter template". Open it in Stastic and publish at the root of this repo.

About pages: the pages in Silex/Stastic are published as layouts in 11ty. Here are the minimum required pages:

page name in Silex layout description
Default _layouts/default.html This layout is used by content/pages/404.md which is the page displayed for non existing pages. Use the default layout when you create other page which need simple design, e.g. just the header, footer and a text.
Page _layouts/home.html This layout is used by content/pages/index.md
Post _layouts/post.html This layout is used by content/posts/*.md. It displays the content of a post.

Links:

Deployment

This starter has everything setup to deploy to github pages, netlify and FTP. Github actions are used to build the site and deploy. You need to create github secrets for the actions to deploy to FTP or Github pages. Depending on where you deploy to, you might have to add environment variables.

About environment variables (env vars) and Github actions secrets

host on github pages

This repository conains an action to deploy on github pages automatically

Here is what you need to do to activate it:

  1. Create a deploy token here with the access write public_repo
  2. In the settings of the website, "secret" section, create a new secret, call it DEPLOY_TOKEN and paste the token as its value
  3. Enable actions in the settings of the repo and in the "Actions" tab

In order to use a custom domain, open your repository settings, "pages" section, set the custom domain there.

host on Netlify

All you need to do is go to netlify.com and import your website from github (select this repository and "eleventy" if it asks for a static site generator)

host on any hosting with FTP/SFTP deployment

Here is what you need to do to activate it:

  1. Enable actions in the settings of the repo and in the "Actions" tab
  2. In the settings of the repository, in the "secret" section, create 1 new secret, per option: ftp_host, ftp_port, ftp_username, ftp_password, ftp_protocol, ftp_path, ftp_local_path - see the meaning of each option in the FTP deployment action docs here and the equivalent docs for SFTP deployment
key value
ftp_host ftp.digitalforest.fr
ftp_port 21
ftp_path /public_html/
ftp_path_staging /public_html/staging/
ftp_username the one created in digital forest admin, e.g. ocr@ocr.internet2000.net
ftp_password the one created in digital forest admin
sftp_private_key the private key (the content of the private key file)
sftp_passphrase key pass phrase

This is what the secret section should look like:

settings of the repository, "secret" section, create 1 new secret

This is the documentation for Silex website builder. It is a collaborative effort, click edit and start contributing. Also have a look at these discussions.

WARNING: Support for Silex v2 has stopped. Try Silex v3 alpha, Read about it, Subscribe to the newsletter

Clone this wiki locally