Skip to main content

Building blocks for my first Eleventy site

I started using Eleventy mainly, because eevis.codes used it for her site! Go check it out. She posts great stuff about accessibility (and knitting)!

Originally I used Wordpress, but felt held back by the UI. I wanted to have the possibility of doing custom HTML more easily.

Adding id's to headings

I want to be able to use anchor links, so I made it possible to generate id's for headings in Markdown.

For this I used Humanwhocodes's post "Eleventy headings ids":

Include the code below into .eleventy.js file:

// this works because Eleventy also installs markdown-it
const markdownIt = require("markdown-it");

// create a new markdown-it instance with the plugin
const markdownItAnchor = require("markdown-it-anchor");
const markdownLib = markdownIt({ html: true }).use(markdownItAnchor);

// replace the default markdown-it instance
eleventyConfig.setLibrary("md", markdownLib);

Language setting

Sometime I might post in Finnish, so I want to have an option to do so. That's why I added a lang attribute to the main section on my blog posts. I have two choices

  1. I can omit it and the overall side language takes over (which is English) or
  2. I can include lang="fi" in the frontmatter and it will change the blog post's language to Finnish (for example).

The code looks like this: <main {{ lang }} id="main"> (I id the main, so I can add "skip to content" link later.)

Teasers and excerpts

You can include teasers in your blog posts. So, I did that. Should it just be the first paragraph of the blog post? Might be easier. Or two first sentences?

How to do this? Include teaser: [teaser text] in your front matter.

Update: I actually didn't use the technique above. I wanted for the site generate the blog excerpt by itself. For this I followed Jonathan Yeon's "Excerpts wit Eleventy" and modified it a bit to work with language tag properly. My issue being that I post in English and in Finnish.

I already got the posts tagged properly, but excerpts didn't have proper language tags. I had to change how the JavaScript function produces the excerpt if the blog has a lang property in the front matter. Then it also includes the lang="fi" attribute for the excerpt.

Code that I used from Jonathan Yeong's post (and modified):

function extractExcerpt(article) {
  if (!article.hasOwnProperty("templateContent")) {
    console.warn(
      'Failed to extract excerpt: Document has no property "templateContent".'
    );
    return null;
  }

  let excerpt = null;
  const content = article.templateContent;
  const lang = article.data.lang;

  excerpt = striptags(content)
    .substring(0, 150) // Cap at 150 characters
    .replace(/^\s+|\s+$|\s+(?=\s)/g, "")
    .trim()
    .concat("...");

  if (lang) {
    excerpt = "<p " + lang + ">" + excerpt + "</p>";
  }

  return excerpt;

Adding pagination

So, not all of the posts are visible in one sitting. Not sure how to do this yet.

Update 1: Pagination still doesn't work...

Update 2: So, yeah. The problem was that I used reverse in the function that produced the list of my posts in the for loops: {% for post in posts %}.

What fixed it was to remove the reverse from the loop and just add reverse to the front matter of my blog page. This allowed the pagination to work properly.

Deploying with Netlify

When I do this, I will probably follow Kevin Powell's instructions on Youtube.

Update: Actually I'm using CodingTheSmartWay's blog post on managing blog content with Netlify.

Adding a hidden "skip to content" link to the top of the page

I followed Paul Ryan's instructions on css-tricks.

I noticed that I had to translate by 105 %, since the edge of the box was poking out from above.

I also had to ditch my margin: 5%; from the body. Have to figure that out.

Support for dateTime stuff with Luxon

I just followed the npm install -route from Luxon.

You cannot believe how hard of a time I had implementing this...

But I finally got it working!

I used Luxon's docs to help me format the date into the format we use in Finland.

Here is the code for that

eleventyConfig.addFilter("postDate", (dateObj) => {
  return DateTime.fromJSDate(dateObj).toFormat("<strong>d.L.yyyy</strong>");
});

I was wondering if I should try to display the date in other languages based on the langauge of the post.

Now I also want to display the publication date after the blog post's heading, but this can't really be done in a straighforward way with a layout... I have to investigate!

Update: I used use Nunjucks's extends which I already use to display h1 headings on individual pages.

Generating the main navigation and implementing aria-current

I followed a guide from Mike Aparicio on "Templating: Eleventy's super power" (Youtube).

I did two things

  1. used Nunjucks functions to render the navigation iteratively and
  2. implemented aria-current that tells the user which page they are on.

I had some difficulties getting the .json to work properly with navigation items, but it finally worked!

Using prism.js to syntax highlight

Including prism.js is pretty straighforward since there is a resource for that too! Just follow 11ty's own instructions on the syntac highlighting plugin.

I just noticed that the background of the code template isn't accessible with comments' font color, so I have to fiddle with that stuff.

Messing around with the CSS

So, much to learn...

I want to

  1. change my headings' size, so they would be bigger and pop up from the text more, they should also have more space before and after
  2. include the "#" to copy anchor links for my posts, it seems cool!
  3. make everything nice and center, I seem to have to learn flexbox for this.
  4. find a good font set to use for the site. I like this one, but I feel like it should have more of an !umph! to it.
  5. decide on the color scheme.

I reminded myself how em and rem work by reading Lawrence Eagles's "Using em vs. rem in CSS on LogRocket

Still not totally sure how they work, but they are relative!

Getting reverse filter working on the post list

My problem was that I wasn't actually using Nunjucks as my templating language, since Eleventy uses Liquid by default. This led to my function's filter not working at all.

I changed my .eleventy.js configuration to such:

return {
    dir: {
      input: "src",
      output: "public",
    },
    templateFormats: ["md", "njk", "html"],
    markdownTemplateEngine: "njk",
    htmlTemplateEngine: "njk",
    dataTemplateEngine: "njk",
  };

And it works!

Update: I detailed earlier that I shouldn't have used this, so now it's been changed to normal flow.

Adding language filtering for posts

If nothing else has been developed then I have to follow instructions laid out here: https://github.com/11ty/eleventy/issues/504.

CSS for readability

I want to check out Andy Bell's "Improve the readability of the content on your website" for CSS tips - especially about creating more space between content.

Not all of it is something I want to incorporate, so I have to go through it with time.

Pagination

I will use Shiv's instructions on this.

Update: Apparently it's really important you use the alias: posts when referring to collections.post. I couldn't get it working until I included it in the front matter.

Now the pagination works (with 5 posts per page) and you can move between pages that show posts! The hiccup now is that they are out of order... I think this is mainly Netlify CMS's fault on how it dates posts, so I have to look into that.

Update 2: This is embarrasing... If I had just read the documentation on Eleventy's site on "Modifying the data set prior to pagination", I would have understood that you shouldn't reverse the whole collections.post, but use reverse: true in the blog's index file. Well, now it's sorted.

Excerpts

I added excerpts to be shown on the blog page, so the reader can have a taste of the contents before committing to reading it. I followed Jonathan Yeong's instuctions on excerpts and I got it working!

Now that I think about it, it might cause a problem if I want to use a table of contents for each post, since that would be the first text on each post. Maybe I can get the function to ignore the table of contents somehow.

Screen reader only text

I already used screen reader only text in the "Skip to content" link at the top of the page, but now I needed to just hide text.

I am using this on my blog page, where after an excerpt you can decide to read the post. For a sighter user the position of "Continue reading" would make it obvious that you are going to move to the post with the title. For a person with blindness it might be harder to understand the context. So, now every "Continue reading" link actually contains hidden text that is simply the title of the post again.

Tabbing out

I am figuring out if opening links to new tabs is accessible or not.

This is something I prefer, but it might not be the best solution: Coder's block write up about opening new tabs.

Using labels

I want to check out W3's instructions on labels. Should be interesting!

I am following 11ty's base blog (GitHub) to implement pages that show all posts with a specific tag.

Sharing posts to social media

I followed Raymond Camden's solutions to this by reading the blog post Adding Social Share Links in Eleventy. I include this function to every blog post for easy sharing.

Because I post in English and Finnish, I have included an if-else statement. If the post has a language attribute (because posts can only have lang="fi", English is the default) then it produces a Finnish text for sharing. Else statement produces the default English text.

I included optional classes to style it later, if I want.

[nunjucks if statement]
<h2 class="share-h">Jaa someen</h2>
<ul class="share">
  <li>
    <a
      href="https://twitter.com/intent/tweet?url=https://samimaatta.fi/en/building-blocks-for-my-first-eleventy-site/&text=Building blocks for my first Eleventy site"
      >Jaa Twitterissä</a
    >
  </li>
  <li>
    <a
      href="https://www.linkedin.com/sharing/share-offsite/?url=https://samimaatta.fi/en/building-blocks-for-my-first-eleventy-site/"
      >Jaa LinkedInissä</a
    >
  </li>
</ul>
[nunjucks else statement]
<h2 class="share-h">Share</h2>
<ul class="share">
  <li>
    <a
      href="https://twitter.com/intent/tweet?url=https://samimaatta.fi/en/building-blocks-for-my-first-eleventy-site/&text=Building blocks for my first Eleventy site"
      >Share on Twitter</a
    >
  </li>
  <li>
    <a
      href="https://www.linkedin.com/sharing/share-offsite/?url=https://samimaatta.fi/en/building-blocks-for-my-first-eleventy-site/"
      >Share on LinkedIn</a
    >
  </li>
</ul>
[nunjucks endif statement]

Anonymous feedback form

Because of gwern.