Reaching for the stars

Editors’ choice: Markdown

Our editorial process is as follows: Once we find an interesting solution, we contact the original author, discuss necessary adaptations or improvements, edit text and images to make it as easy to understand as possible and finally publish the solution on dooiy under an open-sharing license, usually a Creative Commons license.

The result of collecting all this valuable knowledge from individuals and other organizations will be a huge archive some day. Each guide documenting a hack, that can make life easier, maybe it can even safe a life in case of a catastrophe. We know of the fire extinguisher, that it has stopped at least one fire from burning a whole home and possibly spreading even further.

Considering this enormous knowledge asset, we want to store these documents in a way, that will outlive our decisions and whatever the next trend is. We decided, that these documents should be files, that we can edit with a POTE (Plain Old Text Editor).

It was clear soon, that we wanted markdown, but that pure markdown would not be enough.

Markdown +X

As in-house authors and editors, we were willing to write markdown in a text editor, for externs we plan to provide a customized markdown editor. But in the processing pipeline, we want to be able to map markdown nodes to other, potentially more complex HTML structures. E.g. markdown image elements ![My alt text](./relative/image.jpg "photo by Nkosinatho Sambo") should become fully responsive picture elements, maybe even wrapped in a figure.

Looking at what we already implemented up to now, the 20/80 list of our requirements (20% of requirements, covering 80% of our needs) is roughly:

• mapping standard markdown nodes to custom HTML structures, e.g. fully responsive images/pictures from standard markdown images
• including partial markdown files in others
• two handful of custom components generating a snippet of HTML, e.g. to include audio streams, embed YouTube videos (fully EU GDPR compliant), render a beautiful quote with avatar and all the pi-pa-po
• annotating style directives, e.g. .gallery to any markdown node, being passed down to the final HTML element, so we can easily style it with CSS

Astro Magic MDX

Due to it’s amazing flexibility and extendibility, all this can be done with Astro’s🚀 MDX Integration. But if you have used MDX before, you might have noticed that MDX files tend to become quite technical.

For us tech nerds, that is mostly fine, and being able to write the content of our technical documents in Markdown is already a big gain. But for non-tech content-editors, writing this style of markdown is quite a burden, and actually I realized, that it is quite a burden for my mind, too.

So I decided, that our MDX must be much cleaner, much closer to plain markdown, in some places maybe even cleaner. With Astro, we were able to implement a publication pipeline for dooiy.org, that provides content-editors with the ability to write almost clean markdown, with some directives and only a few sprinkles of JSX and without overloading the frontmatter. Because open-source is in our genes, we published all the basic modules of our pipeline as Astro Magic MDX aka astro-m2dx on NPM.

Astro M²DX is a remark plugin, that you can use in your Astro site generator, to keep your MDX close to Markdown, while still using all of the rich MDX features. It even includes feature-rich image optimization for markdown-style images ![Markdown](./image.tags):style{.and-art-direction}!

We launched dooiy.org four weeks ago and are quite happy with the resulting website and the process behind it. Not only is it very fast, it also saves our users high bandwidth-cost and is good for the environment. But we are so busy telling neighbors in the informal settlements around Cape Town about it, that we haven’t managed to migrate our website to Astro 2.0, nor the Astro M²DX plugin. Have a look at the astro-m²dx website, if you are interested anyways.

Who we are

Who we are

dooiy is being developed by Hack Your Shack, a young non-profit organisation from Germany with a passionate team in Berlin and South Africa.

To fulfil our vision, we are looking for partners, volunteers, donors and people who spread the word.

Learn moreand become a partner

• The dooiy project is supported by
• 
•