Render pages from Markdown #138

New Issue

paul · 2018-02-07T21:18:33Z

paul commented

2018-02-07 21:18:33 +00:00

I did preliminary tests, and having a prebuild job turning markdown to flat xhtml is easy.

However:
None of our pages is written in flat simple XHTML.

due to previous design choices almost every page has a multitude of specialised css classes added to its markup. Markdown is not capable of mapping those in a sensible manner. In most cases those classes do not really need to be assigned manually. Proper automatisation would either require assignment by the xsl processor, or a rewrite of the CSS files. I would prefer the latter.
We usually have a few custom attributes in the xhtml header, like for example the newsdate. Markdown files will have to be preprocessed, to support respective header lines.

ToDo

Design pandoc headers for news tags (translatable)
check header fields for author, title, translator, newsdate
find markdown compatible replacement for most common custom CSS classes
how to include the sidebar?
header field for body class

(transferred from Pauls Kan-Board)

I did preliminary tests, and having a prebuild job turning markdown to flat xhtml is easy. **However:** None of our pages is written in flat simple XHTML. 1. due to previous design choices almost every page has a multitude of specialised css classes added to its markup. Markdown is not capable of mapping those in a sensible manner. In most cases those classes do not really need to be assigned manually. Proper automatisation would either require assignment by the xsl processor, or a rewrite of the CSS files. I would prefer the latter. 2. We usually have a few custom attributes in the xhtml header, like for example the newsdate. Markdown files will have to be preprocessed, to support respective header lines. #### ToDo * Design pandoc headers for news tags (translatable) * check header fields for author, title, translator, newsdate * find markdown compatible replacement for most common custom CSS classes * how to include the sidebar? * header field for body class (transferred from Pauls Kan-Board)

paul added the

feature-request

build

labels 2018-02-07 21:18:33 +00:00

reinhard removed the due date - 2019-04-29 21:04:45 +00:00

reinhard referenced this issue

2020-05-13 13:37:15 +00:00

Many pages contain absolute links with fsfe.org #1378

max.mehl referenced this issue

2020-05-13 14:25:47 +00:00

Many pages contain absolute links with fsfe.org #1378

max.mehl commented

2021-01-21 15:19:13 +00:00

In the Web Meetup 2021-01-19, we've concluded the following goals and ideas:

We want to start with simple pages, so standard news items and newsletters, to not have to overload the system from the start.
The goal is not to convert all existing pages to Markdown, but instead allow editors to use Markdown for new content.
We said that it makes most sense to convert a Markdown file to XHTML first, and then run this through our build system normally.
An open discussion is the choice of the Markdown dialect. We considered the dialects used by Gitea or Hugo to be the optimal choice to be friendly to new editors.
We probably need shortcodes for special tags like our modules or figures. Hugo's shortcodes can be an inspiration for the format, but eventually our converter has to understand it.

In the Web Meetup 2021-01-19, we've concluded the following goals and ideas: * We want to start with simple pages, so standard news items and newsletters, to not have to overload the system from the start. * The goal is not to convert all existing pages to Markdown, but instead allow editors to use Markdown for new content. * We said that it makes most sense to convert a Markdown file to XHTML first, and then run this through our build system normally. * An open discussion is the choice of the Markdown dialect. We considered the dialects used by Gitea or Hugo to be the optimal choice to be friendly to new editors. * We probably need shortcodes for special tags like our modules or figures. Hugo's shortcodes can be an inspiration for the format, but eventually our converter has to understand it.

delliott referenced this issue

2025-04-27 14:08:49 +00:00

Ease the process ODT2NewsItem #3054

delliott commented

2025-04-27 14:14:30 +00:00

Some years later, we hope to pick this up and continue working on it.

The sensible thing to do is probably to move to having an intermediate XHTML file called something like .<name>.<lang>.xhtml, which would be a git ignored pattern. This file would be either a symlink to either <name>.<lang>.xhtml if available, or be generated from a <name>.<lang>.md file.

The symlinking should not incur too much of a performance penalty. And if we take care and use a compiled library for the markdown parsing we should get pretty performant markdown conversion.

We should probably try and stick closely to commonmark all right. Shortcodes would be ideal, but for the start we can probably get away with just embedding html directly? See here. I am not sure we want to have the effort of implementing a shortcode parser thing.

Pinging @sofiaritz as person planning on working on this.

Some years later, we hope to pick this up and continue working on it. The sensible thing to do is probably to move to having an intermediate XHTML file called something like `.<name>.<lang>.xhtml`, which would be a git ignored pattern. This file would be either a symlink to either `<name>.<lang>.xhtml` if available, or be generated from a `<name>.<lang>.md` file. The symlinking should not incur too much of a performance penalty. And if we take care and use a compiled library for the markdown parsing we should get pretty performant markdown conversion. We should probably try and stick closely to commonmark all right. Shortcodes would be ideal, but for the start we can probably get away with just embedding html directly? See [here](https://spec.commonmark.org/0.31.2/#raw-html). I am not sure we want to have the effort of implementing a shortcode parser thing. Pinging @sofiaritz as person planning on working on this.

sofiaritz commented

2025-05-10 09:15:31 +00:00

My initial design ideas are pretty similar to those suggested by @delliott. I agree that we should adhere to a open and widely adopted Markdown standard, such as Commonmark.

Here's what I landed on after experimenting for a while, for readability purposes I kept the examples shorter:

From a publisher's perspective, they would create a Markdown file that looks like the following:

---
layout: "news_item"
title: "Simplifying FSFE translation process: integrating LibreTranslate"
teaser: "A new release of the Webpreview tool is here! This is our in-house Free Software preview tool for FSFE webpages."
newsdate: "2025-04-29"
(...)
---

As an European charity promoting the use of Free Software as well as the importance of software freedom. One of our ways of reaching the Free Software community, and the society in general, is by offering our website and documents in several languages – translated by native speakers. 

(...)

That Markdown file would then be rendered into the "news_item" template, which could be implemented using a open and widely adopted template format, such as Liquid.

The pipeline would then look like this:

Markdown → Partial (X)HTML
Partial (X)HTML and data from the frontmatter → Liquid compiler → Final XHTML
Final XHTML → into .<name>.<lang>.xhtml

This could also allow us to use Liquid features from Markdown, which includes filters and tags. This would allow us to implement thing such as {% peertube link="..." %} with ease.

My initial design ideas are pretty similar to those suggested by @delliott. I agree that we should adhere to a open and widely adopted Markdown standard, such as Commonmark. Here's what I landed on after experimenting for a while, for readability purposes I kept the examples shorter: From a publisher's perspective, they would create a Markdown file that looks like the following: ```md --- layout: "news_item" title: "Simplifying FSFE translation process: integrating LibreTranslate" teaser: "A new release of the Webpreview tool is here! This is our in-house Free Software preview tool for FSFE webpages." newsdate: "2025-04-29" (...) --- As an European charity promoting the use of Free Software as well as the importance of software freedom. One of our ways of reaching the Free Software community, and the society in general, is by offering our website and documents in several languages – translated by native speakers. (...) ``` That Markdown file would then be rendered into the "news_item" template, which could be implemented using a open and widely adopted template format, such as [Liquid](https://shopify.dev/docs/api/liquid). The pipeline would then look like this: - Markdown → Partial (X)HTML - Partial (X)HTML and data from the frontmatter → Liquid compiler → Final XHTML - Final XHTML → into `.<name>.<lang>.xhtml` This could also allow us to use Liquid features from Markdown, which includes [filters](https://liquid.readthedocs.io/en/latest/custom_filters/) and [tags](https://liquid.readthedocs.io/en/latest/custom_tags/#usage). This would allow us to implement thing such as `{% peertube link="..." %}` with ease.

👍 1

Sign in to join this conversation.

4 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: FSFE/fsfe-website#138