From Dotclear to Eleventy 5
The task
With dotclear, I had a ready made publication managment that comes with all blog engine. Switching to a static site I wanted to keep the option for keeping drafts. I that I wanted to keep with my static site, even if I needed to adapt a bit. This are related to publication managment, recuring links that I liked to add after my articles, abstracts and of course search.
Drafts and publication managment
The previous blog could manage drafts, articles that I started to write, that I want to save but are not ready to publish.
As I am using git to manage the code history, I could just create a branch with the article name and only merge it when I want to publish.
But my preference goes to a solution where drafts are saved into the main branch so I can edit them when I am working on another article.
For this, all I had to do was to mark in the front matter that the page is not generated in the static site. I chose to use exsting properties instead of a custom “draft” attribute that would need custom development.
# UNPUBLISHED
permalink: false
eleventyExcludeFromCollections: true
eleventyExcludeFromCollections means that the article will not be liste din any index or search and permalink that there won’t be a page for it in the static site.
Publishing a draft article is as simple as removing thoses 3 lines and push release the change to production.
Listing all draft articles is as simple as searching for the lines with # UNPUBLISHED on the entiere project.
Subfooters for recuring links
The old site also had many “related links” posted at the end of articles. They were just html blocks copied and pasted at the end of the article content. I know that with eleventy, I can do better.
Under /static/subfooter/ I created a bunch of html files containing the HTML code from the old blog. Then, I added their names in the front matter of all articles where I wanted them to display. I allowed myself to add more than one.
subfooters:
- velos
- expo
- cliches
With the migration, all articles already had subfooter coded just as content at the bottom of their template. This code was easy to find by just searching for the right HTML string. All I had to do then was to add the corresponding name in the front matter and remove the hugly code from the templates.
I could make a script to do it all at once but I took time to do it manually on all articles to make sure I add the relevent subfooter.
Rendering subfooters
Once the subfooters were added in the front mater on templates, the layout had to take them into account and render the HTML right above the footer.
This was done with the help of Render Plugin imported in eleventy config.
// allows to include subfooters
const { RenderPlugin } = await import("@11ty/eleventy");
eleventyConfig.addPlugin(RenderPlugin);
The plugin then allows me to use renderFile with a file path in the layout.
{%- for subfooter in subfooters -%}
{% set filePath = "{% renderFile './src/static/subfooter/"+subfooter+".html' %}" %}
{{ filePath | renderContent("njk") | safe }}
{%- endfor -%}
Note that we can’t simply use renderFile. Nunjunk doesn’t support to use renderFile with a variable in the file path. The solution is to use the filter `renderContent on the file path that is set just before.
Because we can’t chain filters, markdown is not supported, and files that are included have to be in plain HTML. Also, the page will not hot-reload when the subfooter is modified. If you know solutions to solve this I’d be happy to hear from it. For now, I am happy with the current progress.
The result is a managment of related links much better than before. A few lines is the front matter of a page.
subfooters:
- drooderfiets
- velo
will add the following at the bottom of the page:
Article abstracts
In the old blog, abstracts and content were two different pieces of data that were then displayed one after the other on article pages. The index page though, was only listing abstracts and link to the article pages.
For the new blog, I wanted to keep the same behaviour with two levels of content but keeping the principle of one article = one template = one file. I decided to just add a separator within the content, in the article template. Nothing else.
<!-- excerpt -->
Eleventy will then recognise the separator thanks to setfront matterParsingOptions and add page.excerpt in the data related to the article. Just as if it would be added in the front matter.
// allow excerpt
eleventyConfig.setfront matterParsingOptions({ excerpt: true,
excerpt_separator: "<!--excerpt-->"
});
The Index layout then, can use it to display the abstract and a read more link for each post.
{% if post.data.page.excerpt %}
<p class="text-justify justify-content"> {{ post.data.page.excerpt | md | safe }}</p>
{{ readMore(post.url) }}
{% else %}
The | md after the text of the abstract is formated with Markdown. For this purpose a filter has been added in the eleventy config.
eleventyConfig.addFilter("md", function(rawText) {
if (!rawText) return;
return mdLib.render(rawText);
});
Normal article page will not use this piece of data and display the whole content, including the excerpt, just as it should. The code <!-- excerpt --> doesn’t even appear in the code because eleventy cleans out all comments.
Search
Search implementation was quite simple. It came from huwindity and was used as it came. Well not exactly, I made changes so it loads only when necessary.
These changes were later added to Huwindty and documented on the starter website. This is where you will read text to know more about it.
Note that the search is powered by pagefind that manages to surface pages with related matching including typos and plurals for example.
On the example above, many pages related to tulipes are listed for a search on tulips.