Reaching for the stars
How Astro helps us to create everything out of Markdown +X
At dooiy we set out to make actionable open-source knowledge accessible to everyone anywhere. Therefore we are continuously on the hunt for clever solutions that are easy to reproduce and can help make life easier. We especially focus on people whose life isn’t that easy, mainly due to extreme poverty.
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.
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
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.
.galleryto 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
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.
What is dooiy?
On dooiy you find fun and easy hacks that make life easier. Just follow our simple step-by-step guides and create something for your home or community with little materials and tools. Want to start a business? dooiy might be the perfect starting point for you.
You don‘ t have to be an expert to start making with dooiy. Just choose an easy hack and get going. After you made a few, I am sure that you will come up with your own ideas.
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