Polyglot Tech Blog

Get started with Polyglot Tech Blog template

Florent Tassy — Sun, 09 Jul 2023 14:00:00 +0000

Introduction

You have found Polyglot Tech Blog and wish to use it as a basis for your blog. Great! Let's go through the steps to get the code and adapt it to your needs.

Get the code and install the dependencies

First, you need to get the starter code. The easiest way to do this is to use git. Go to the directory where you want to get the files, and clone the repository:

git clone https://gitlab.com/florent_tassy/polyglot-tech-blog.git

Then you need to install the template dependencies. For this, you need node and npm or Yarn. Go to the newly cloned directory and enter:

npm ci # with npm
yarn install --frozen-lockfile # with Yarn

Launch the local server and adapt the starter

You now have everything. You can start the dev server to see a local and auto-refreshed version of your code. From the template directory, run:

npm run dev # with npm
yarn dev # with Yarn

You can now open you favorite web browser, navigate to localhost:8080, and see the live result!

Adapt the content

The first customisation that you will probably want to bring is changing the content. To do so, here are the needed concepts:

The content is in the "src" directory.
Static pages are written in HTML with template parts in Nunjucks, but keep in mind that Eleventy offers many more languages.
Blog posts are written in Markdown, but here as well, other languages could be used.
The files directly in "src" are mainly configuration files and technical files. You may change the content of index.html and 404.html, but these files are not supposed to be displayed, unless the redirection to local or fallback language fails. You will also add / modify your files for deployment.
You should update the file src > data > data.json with your information. Here are some useful comments about it:

{

    // Full name of the blog author
    "author": "Florent Tassy",

    // Optional, but nice for semantic
    // web: the unique URI that 
    // identifies the author. Avoid
    // using a URL of the blog or you
    // may get weird ID associations.
    "authorUri": "https://gitlab.com/florent_tassy",

    // BCP 47 codes of the languages 
    // used on the blog. 
    // The first one is the default 
    // one. At least one is needed.
    "languages": [ "en", "fr" ],

    // Language labels. 
    // All above declared codes 
    // must have a corresponding 
    // entry here.
    "languageLabels": {
        "en": "English",
        "fr": "Français"
    },

    // Blog title. 
    // All above declared codes 
    // must have a corresponding 
    // entry here.
    "title": {
        "en": "Polyglot Tech Blog",
        "fr": "Polyglot Tech Blog"
    },

    // Optional, but nice for semantic
    // web: the URIs that identify
    // the blog languages. 
    // http://lexvo.org and 
    // https://dbpedia.org provides
    // interesting resources here
    "languageUris": {
        "en": "http://dbpedia.org/resource/English_language",
        "fr": "http://dbpedia.org/resource/French_language"
    },

    // URL the blog will be deployed to. 
    // Don't put a trailing "/". 
    // I recommend to leave it as it is 
    // and subsitute it with the final 
    // URL at deployment time.
    "baseUrl": "http://localhost:8080",

    // General blog keywords. 
    // They will be used in the <meta> 
    // tags of all pages. 
    // Here as well, each code defined 
    // in languages must have a 
    // correspondance.
    "keywords": {
        "en": "polyglot, multilingual, blog, eleventy, 11ty, starter, template",
        "fr": "polyglotte, multilingue, blog, eleventy, 11ty, départ, modèle"
    }
}

You may personalize src > index.html and src > 404.html, but that's not absolutely necessary.

Adapt the style

You can go to the article about colors for further details about this step.

Add or remove languages

Removing a language is simply deleting the corresponding directory and updating the src > _data > data.json file accordingly. When adding a new language, there are a bit more things to consider, so you can consult the dedicated article.

Add static pages

The starter comes with four static page: "Home", "About", "Blog" and "404". They are written in HTML and can be found in each language directory:

src
 ├── (all files in src)
 ├── en
 │   ├── index.html <- the "home" page
 │   ├── about.html
 │   ├── blog.html
 │   └── 404.html
 └── fr
     ├── index.html <- the "home" page
     ├── about.html
     ├── blog.html
     └── 404.html

You may decide to add some static pages. Here as well, there is a dedicated article that covers the topic.

Add posts

This is probably the most basic thing expected from a blog start. You can do this by following the instructions on the dedicated article

Check markup validity

The starter template comes with commands and dependencies to check HTML and CSS validity using W3C's vnu-jar. However, vnu-jar checker is written in Java, so you will have to install a Java Runtime Environment to make these commands work. I recommend the free and excellent Eclipse Temurin.
You can then check the HTML validity with:

npm run check:markup:unix # with npm on Linux and unix-like systems
yarn check:markup:unix # with Yarn on Linux and unix-like systems

npm run check:markup:win # with npm on Window systems
yarn check:markup:win # with Yarn on Windows systems

You can then check the CSS validity with:

npm run check:css:unix # with npm on Linux and unix-like systems
yarn check:css:unix # with Yarn on Linux and unix-like systems

npm run check:css:win # with npm on Window systems
yarn check:css:win # with Yarn on Windows systems

Check various metrics about your blog

The number of things you can check to ensure the accessibility (a11y), performance, Search Engine Optimization (SEO), validity... of a website is unlimited and may require some advanced skills or tools. Some simple and basic checks are covered in the dedicated article

Build and deploy

Our blog is ready to be put online. This can bon done on multiple ways depending on where your code is and who hosts the blog. This article covers some common scenarios.

Conclusion

We have seen all basic steps to get a Polyglot Tech Blog up and running with your content. If you followed all these steps, you have now an online blog. Congratulations! Of course, many more customizations are possible, so feel free to experiment and share your ideas on GitLab 😉

Customize the colors

Florent Tassy — Wed, 05 Jul 2023 14:00:00 +0000

Introduction

The colors of a web page are the most fundamental thing to choose in order to feel at home and to reflect who we are. Let's see where Polyglot Tech Blog colors are defined in order to modify them.

Modify the right file

Polyglot Tech Blog supports supports SASS files. It also includes Chota micro CSS framework. It is a single CSS style sheet that provides enough to style what we want.

The Chota colors are ready to be overriden in the src > sass > style.scss file. The 40 first lines contain CSS variables and attribute their values for light and dark themes:

:root {
    --bg-color: #ffffff;
    --bg-secondary-color: #f3f3f6;
    --color-primary: #14854f;
    --color-lightGrey: #d2d6dd;
    --color-grey: #747681;
    --color-darkGrey: #3f4144;
    --color-error: #d43939;
    --color-success: #2c8017;
    --font-color: #333333;
    --navbar-bg-color: #f8bb6d;
    --footer-bg-color: #f8bb6d;
    --transparent-error: rgba(255, 194, 204, 0.3);
    --transparent-success: rgba(145, 238, 145, 0.3);
    --link-color: #333333;
    --grid-maxWidth: 120rem;
    --grid-gutter: 2rem;
    --font-size: 1.6rem;
    --font-family-sans: sans-serif;
    --font-family-mono: monaco, "Consolas", "Lucida Console", monospace;
    --content-width: 75%;
}

.dark-theme {
    --bg-color: #222222;
    --bg-secondary-color: #333333;
    --color-primary: #4cad7e;
    --color-lightGrey: #323232;
    --color-grey: #747681;
    --color-darkGrey: #8794a8;
    --color-error: #d43939;
    --color-success: #28bd14;
    --font-color: #dddddd;
    --navbar-bg-color: #741e00;
    --footer-bg-color: #741e00;
    --transparent-error: rgba(255, 194, 204, 0.3);
    --transparent-success: rgba(145, 238, 145, 0.3);
    --link-color: #dddddd;
}

Changing colors of the whole webpage is basically just changing the variable values in this file.

Syntax highlight

If you plan to use syntax highlighting, you may wish to change the highlighting style as well. As you can imagine, this happens in the files src > css > code-highlight-dark.njk and src > css > code-highlight-light.njk.

These two templates actually contain CSS and result in two CSS style sheets that are alternatively added depending on the selected color schema. By default, the light theme is the "prism-coy" theme provided with PrismJS. Any theme provided as an NPM package could be added the same way.

The dark theme is based on Gruvbox dark theme by Azat S.. However, it was a bit modified to pass the automated accessibility tests done by axe browser extension. So in that case, the CSS code was simply copied and modified in the src > css > code-highlight-dark.njk file.

Conclusion

We have seen what files we have to modify or replace to change our blog colors. But be wise when choosing your colors and keep in mind that accessibility depends a lot on colors contrast. If you want to assess the accessibility of your color schema, the article about blog metrics should give you more insight.

Add language

Florent Tassy — Sun, 02 Jul 2023 14:00:00 +0000

Introduction

Polyglot Tech Blog comes in English and French to show in action. However, it is possible to add as many languages as you want. Let's show how by adding German 🇩🇪

Update data.json

Simply add the new language:

src > _data > data.json:

{
    // Other properties
-   "languages": [ "en", "fr" ],
+   "languages": [ "en", "fr", "de" ],
    "languageLabels": {
        "en": "English",
-       "fr": "Français"
+       "fr": "Français",
+       "de": "Deutsch"
    },
    "title": {
        "en": "English",
-       "fr": "Français"
+       "fr": "Français",
+       "de": "Deutsch"
    },
    "keywords": {
        "en": "blog, english",
-       "fr": "blog, français"
+       "fr": "blog, français",
+       "de": "blog, deutsch"
    }
}

Create the language directory

The simplest first step here is probably to copy an existing language directory, let's say "en", paste it into the src directory, and rename it to the language code you want. Here, we will the rename to directory "de". So we get this strusture:

src
 ├── (all files in src)
 ├── en
 ├── fr
 └── de

The folder name must be BCP 47-compatible language tag.

Change the new directory content

First, rename the en.json file to de.json. Then open it and update the translations and the language.

src > de > de.json:

{
    "lang": "de",
    "home": "Startseite",
    "blog": "Blog",
    "about": "Über",
    "madeBy": "Erstellt von",
    "seeOn": "Überprüfen Sie es auf",
    "read": "Lesen",
    (...)
}

(Here, you should notice that I don't speak German...)

Then go to the blog directory, open the blog.json file, and update the "en" tag to "de":

src > de > blog > blog.json:

{
  "layout": "article.html",
  "tags": [
    "post",
-    "en"
+    "de"
  ]
}

Update the permalinks

Ensure that no permalink in the "de" directory points to a "en/..." URL.

Now, the longest part if you have some content already...

Translate all the pages and blog posts to German!

Change default language

If you want to change the blog default language, please also update the "defaultLanguage" property in .eleventy.js.

Conclusion

That's it, we have added a new language to our webpage! More information on 11ty i18n documentation

Add a static page

Florent Tassy — Fri, 30 Jun 2023 14:00:00 +0000

Introduction

Polyglot Tech Blog comes with three pages:

Home, the landing page
About
Blog, where all blog posts are listed ... as well as a 404 error page.

What if I want to add another static page? Let's add a "portfolio" page to demonstrate it.

Add the files

In each of your language directory, create a file "portfolio.html". This name must be the same accross all your language directories. The file name determines what the page URL will be. Here, it will be something like https://<my-domain>/<language>/portofio.html.

You should get the following structure:

src
 ├── (all files in src)
 ├── en
 │   ├── (all files in en)
 │   └── porfolio.html
 └── fr
     ├── (all files in fr)
     └── portfolio.html

Create the content in your files with the front matter as shown below.

en > portfolio.html:

---
title: "Portfolio"
layout: "base.html"
---

<div class="container">
    <p>
        Here is my content. <br>
        I write it in English in the "en" directory. <br>
        And of course, I write it in French in the "fr" directory.
    </p>
</div>

👍 Done, you have a new page!

Optional: Add entries to the navigation bar

This step is optional. If you wish to have a link to your portfolio page in the navigation bar, you have to make the following modification.

src > _includes > components > navbar.html:

        <!-- Pages -->
        <div class="tabs">
            <a href="{{ '/' | locale_url | url }}">{{ home }}</a>
+           <a href="{{ '/portfolio' | locale_url | url }}">{{ portfolio }}</a>
            <a href="{{ '/about' | locale_url | url }}">{{ about }}</a>
            <a href="{{ '/blog' | locale_url | url }}">{{ blog }}</a>

And finally, the {{ portfolio }} references a variable that must be added to the en.json and fr.json files.

src > fr > fr.json:

{
    "lang": "fr",
    "home": "Accueil",
    "blog": "Blog",
    "about": "À propos",
    "madeBy": "Codé par",
    "seeOn": "Retrouvez-moi sur",
-   "read": "Lire"
+   "read": "Lire",
+   "portfolio": "Portefeuille"
}

src > en > en.json:

{
    "lang": "en",
    "home": "Home",
    "blog": "Blog",
    "about": "About",
    "madeBy": "Made by",
    "seeOn": "Check it out on",
-   "read": "Read"
+   "read": "Read",
+   "portfolio": "Portfolio"
}

Now, your page is accessible from the navigation bar 🥳

Conclusion

We have added a new "Portfolio" static page to our blog. This opens up many possibilities 🤩

Add a post

Florent Tassy — Fri, 23 Jun 2023 14:00:00 +0000

Introduction

A blog is basically made of a few static pages and many articles. Let's see then how we can create a new article in all that languages that our blog supports.

Create the files

This is probably one of the easiest things to do with the template. When we want to add posts, we juste create a file with the same name in every language directory. Let's say I want to post about dolphins in Arctic in my English / French blog. I will add the two following files:

src
 ├── (all files in src)
 ├── en
 │   ├── (all files in en)
 │   └── blog
+│        └── dolphins-in-arctic.md
 └── fr
     ├── (all files in fr)
     └── blog
+         └── dolphins-in-arctic.md

The suggested format here is Markdown, however other 11ty supported formats would also work.

Add content to files

In each newly added files, I can now add your content. But before all, the following front matter is expected:

title: Dolphins in Arctic (To be translated in the fr directory)
description: A blog post about dolphins in Arctic (To be translated in the fr directory)
date: 2010-05-25T12:00:00
update: 2023-05-28T12:00:00 (This one is optional, but if you are actually updating 
an existing article, you can put the update date here)
author: Author name here, that can be different from the src > _data > data.json > "author"
tags: 
    - dolphin (to be translated in the fr directory)
    - Arctic (to be translated in the fr directory)

For the rest, please note that:

Eleventy will automatically add a level one title from front matter. You will then have to add level two and lower titles to keep a valid HTML;
Should you wish to include a link to another blog article, let's say example.md, you could use the following syntax: [hyperlink text]({{ '/blog/example' | locale_url | url }});
Should you wish to include a link to a static blog resource (document, image...), you could use the following syntax: ![description de l'image]({{ '/img/image.png' | url }}).

Done ✅ my new posts is now available at https://<my-domain>/<language>/blog/dolphins-in-artic.

Conclusion

Through this example, we have added a new article to the blog. As you have seen, it takes only two steps, so you may quickly remember this by heart 😉

Check blog metrics

Florent Tassy — Thu, 15 Jun 2023 14:00:00 +0000

Introduction

We are now going to verify a few metrics and present some simple and user-friendly tools to ensure our blog's validity, performance, accessibility and SEO. Those topics are potentially infinite and highly specialized, that is why we will just touch on each of them with automated tools.

Lighthouse

A good way to quickly and simply check webpages performances is by using Lighthouse. It is available in the DevTools of Chromium-based web browsers, which means it can be used when developping on localhost. It is also available as an online service through PageSpeed Insights, but it means that the page must be hosted online already.

Lighthouse provides metrics and advices about performance, accessibility, SEO and other best practices, and it can run in both desktop or mobile configuration. Do not underestimate the mobile devices because more than half of webpage are browsed from mobile device per statcounter.

Accessibility

When it comes to accessibility, WAVE and axe Tools are very nice ways to automatically check how your webpage perform. A very simple way to use it is to install the WAVE and axe DevTools browser extensions. They both runs for local and online page and provides plenty of good advices and checks such as color contrast.

Code validity

For code validity, you probably know already that the Polyglot Tech Blog template allows checking HTML and CSS validity using W3C's vnu-jar. However, W3C maintains plenty of other useful tools that can be used to check yor code validity. Let's mention the internationalization and feed checkers, just to quote some that are applicable to the Polyglot Tech Blog.

Conclusion

We have seen different tools to assess and improve your code in terms of validity, performance, accessibility and SEO. But in the end, all these elements are closely related: invalid code is not properly parsed, leading to performance issues, and then it is not well managed by accessibility tools and badly referenced by search engines. These tools just provide different point of views and advices about your code. They are complementary and, since they are all automated tools, they have some limit in what they can detect.

Deploy

Florent Tassy — Sun, 11 Jun 2023 14:00:00 +0000

Introduction

Now that we have adapted the template with our content, we would like to deploy it on the web. Let's go through some common deployment scenarios.

Deploy manually

In order to have correct hyperlinks, you need to know the URL the website will be deployed to. Create a file named prod.js at the blog root and provide the base URL of your website and the directory in which it is deployed if any. For example, if the URL will be https://example.com/subpath, the file should contain:

module.exports = { 
    baseUrl: "https://example.com/subpath", // Notice that there is no trailing "/"
    pathPrefix: "subpath" 
};

If there is no subpath, leave the value empty: pathPrefix: "". If there is a subpath, you can also delete the robots.txt file as it will not be reachable.

We can now build the blog i.e. process all files in the src directory and generate the HTML, JavaScript, CSS and other static files that will be pushed to the server. I recommend following the steps below:

Stop the dev server if it is running
Empty the public directory

npm run clean # with npm
yarn clean # with Yarn

Build the deployment-ready blog

npm run manual:build # with npm
yarn manual:build # with Yarn

You can then copy the content of the public directory on the server.

Deploy on GitLab pages

The starter comes with a .gitlab-ci.yml file that should do the trick. You will just have to update the gitlab-pages.js file:

module.exports = { 
    baseUrl: "https://florent_tassy.gitlab.io/polyglot-tech-blog", // Notice that there is no trailing "/"
    pathPrefix: "polyglot-tech-blog" 
};

Then push the repository on your GitLab instance. If the remote repository is correctly configured, the CI/CD pipeline will deploy the blog.

Deploy on Netlify

You can refer to Netlify documention.

For manual deployment, the starter comes with a netlify.js file that you can adapt to get the correct build:

module.exports = { 
    baseUrl: "https://polyglot-tech-blog.netlify.app", // Notice that there is no trailing "/"
    pathPrefix: "" 
};

You can now build the blog by following the steps below:

Stop the dev server if it is running
Empty the public directory

npm run clean # with npm
yarn clean # with Yarn

Build the deployment-ready blog

npm run netlify:build # with npm
yarn netlify:build # with Yarn

You can then connect to Netlify and drag-and-drop the public directory.

Deploy on GitHub

The starter comes with a .github > workflows > build-and-deploy.yml file that should do the trick. You will just have to update the github-pages.js file:

module.exports = { 
    baseUrl: "https://ftassy.github.io/Polyglot-Tech-Blog", // Notice that there is no trailing "/"
    pathPrefix: "Polyglot-Tech-Blog" 
};

Then push the repository on GitHub. If the remote repository is correctly configured, the GitHub Action will deploy the blog.

Conclusion

We have covered our blog deployement either manually on a server or on GitLab Pages, GitHub Pages and Netlify hosting services. If your scenario is not covered here, you should find a way to adapt on of these scenarios to your specific case. Congratulations, your blog is now online!