No, it works.
Okay.
Gotta get, there we go.
So, thank you very much and enjoy.
Yep, thank you.
But before I get started, is this readable in the back or do we need to blow it up?
A little bit bigger.
How about this?
Okay, good.
All right.
So, welcome to my talk on materials for MKDUX.
Let me quickly introduce myself and my co-speaker, author.
So, Martin isn't here today, but...
So, I'm Kenneth Hosta.
I'm an HPC system administrator at Gantt University.
HPC is high-performance computing, supercomputing.
Some people may not know this, but it's lots of servers, lots of noise, lots of money,
lots of annoying users as well.
There's a lot going on there.
I'm the lead developer of EasyBuild for the last decade.
So, EasyBuild is a tool for installing scientific software on supercomputers.
It gets a lot, it gets very fun, I can tell you.
I'm involved in way too many FOSS projects.
I patch things and try to fix things left and right.
And I've been attending FOSSDOM since 2013.
If you think FOSSDOM is total chaos, you should try organizing a dev room,
doing a talk and planning live demos during your talk, which is what I'm going to do.
So, I actually had to run out of the HPC dev room, which I'm co-organizing.
I'm a big fan of Material for MKDocs since I discovered it,
and I think more people should know about it, so that's why I'm here.
The other person on the talk as an author is Martin.
Martin Donut, he's the lead developer of Material for MKDocs.
I reached out to him to ask him, please submit a talk on Material for MKDocs to FOSSDOM.
He said, I can't make it this year, then I said, OK, I'll just do it myself.
And I had a call with him to discuss what should be in the talk, so he's been involved.
All right, so why do I want to give this talk?
Well, Material for MKDocs is great.
More people should know about it, more people should be using it.
It's very easy to install and use.
You get very good results with pretty minimal effort, and I'll actually show this hands-on.
Tons of great features.
It's actively developed.
It's open source, of course.
And there's a very interesting part of how it's funded as well,
and I'll cover that as well.
And I was very shocked that there's never been a talk ever at FOSSDOM on MKDocs or on Material for MKDocs.
That's just wrong to me, so I'm here to fix that.
My personal journey is, I've actually haven't been using it for very long.
It's pretty recent, basically, since 2021.
I had to create a tutorial website, or I wanted to create a tutorial website for EasyBuild,
for the tool I'm mostly working on.
The existing EasyBuild documentation was in Sphinx.
I wasn't terribly happy with that.
It felt slow.
It was using RST.
The syntax didn't make sense to me.
It was very difficult to work with.
We were not getting a lot of contributions to that documentation,
so I was looking for other things that could be possible.
The tutorial was a totally new project, a totally new website, and I started looking around.
I found Material for MKDocs, and I was sold after like five minutes.
That tutorial was built with Material for MKDocs, and shortly after we started porting EasyBuild documentation,
also our HPC documentation in Gantt, we also started porting that to Material for MKDocs,
because it just made a whole lot more sense and was a lot easier to use.
And also new projects that I've started since then have always been using this tool
to create documentation and tutorials.
So to start with, what is MKDocs?
How many people here are familiar with MKDocs?
Who has used MKDocs?
About half of the room. Good.
MKDocs is a static site generator.
It's not a very complex tool, I think.
It has a very strong focus on building documentation for software,
so technical documentation, code, all these kind of things.
The documentation sources themselves are written in Markdown,
which is one of the things that sold me to MKDocs.
Markdown is everywhere.
If you're doing pull requests on GitHub or GitLab, issues, formatting there,
Wikis, it's all Markdown, so the documentation that you're writing should also be Markdown,
just to make the jump a bit smaller.
To configure MKDocs, so how the site should look like and all the bells and whistles it has,
that's all done in a single YAML file.
Maybe you don't like YAML, but at least it's a single file that you want to look into
and figure out how to configure it.
MKDocs itself is implemented in Python.
That's other than when you install it, you don't really notice that.
That's probably a good thing.
But it is very easy to install, use, customize, and extend.
So how do you get started with MKDocs?
This is a bit of a long list.
You install it, pip install MKDocs, basically.
You started creating a landing page, so an index.md and a docs folder.
Typically, you can change that if you want to.
You create a minimal configuration file, and then you launch MKDocs.
You do MKDocs build that will take the Markdown that you put in the index.md.
It will generate an index.html from that.
You can open it in your browser and you're good to start with your documentation site.
You can do MKDocs build strict as well.
If you have any mistakes in your documentation, like you're linking to a page that doesn't exist,
for example, it will go ahead and warn you about that.
And that's very useful in CI.
If you're making changes to your documentation,
you can run this in GitHub Actions, for example,
and it will warn you that something is wrong and you shouldn't be merging those changes.
There's a way to live preview the documentation while you're editing it as well through MKDocs.serve.
I'll show you that as well.
And now you can go ahead and write your documentation.
So showing all of that on the slide is very boring, so let's do it hands-on.
And let's see how quickly this goes wrong.
All right, so I'm essentially starting here from an empty folder.
There's an empty docs directory, just so I don't forget to put stuff in there.
The first thing we'll have to do is install MKDocs.
It's not here.
So this is just to pip install MKDocs.
If you're a little bit familiar with Python, you know you have to be careful if you do pip install
because it may end up got those somewhere.
So what I want to do here is create a Python virtual environment.
If I remember how to do that, all right, so now I'm in the virtual environment
and in here I can just do pip install MKDocs.
And if the Wi-Fi works, that should be working.
So now I have MKDocs available, whatever version is there.
Okay, so that's the pip install part, that's step one.
Now I can create a very minimal MKDocs.yaml.
And all you really need to put in there as a very minimal thing is the name of the site.
So let's just toss them here.
And in the docs folder, we want to create an index.md in markdown.
So let's say hello fosdem, this is a demo.
Okay, that's all we need.
We do MKDocs build.
This should be very quick.
It generates a site directory with a whole bunch of stuff in there including index.hdml.
We can open this in our browser and it looks like this.
Hooray, it works.
We even get a search function here.
Of course now there's not a lot to search yet.
You can search for fosdem and it will bring me to that page.
Okay, so the search functionality is already built in and ready to go.
Now once you start creating a couple more pages, let's say getting started.md.
Like this, if you save this, you have to do MKDocs build again.
And you have to refresh this site.
And then here you see there's a getting started page as well.
Now Firefox gets a bit confused because this is all static html.
So it says what do you want to do?
I want to open the page.
What's more interesting if you do MKDocs serve.
So now you're getting a small web server here running locally.
You can click this.
You see the same website.
But when you start changing stuff, for example, in an existing page, let's say magic happens.
As soon as I've saved this and I switch back to the site, this should not refresh.
Oh right, okay.
See demos always go wrong.
Try again.
You save it and if you switch back it pops up there.
So you're automatically getting live preview while you're editing the documentation.
To me this is absolutely brilliant.
Okay, now what I don't like about this is this theme.
Like what the hell is going on?
The lines are white and getting started is here.
Where's my hello page?
So weird stuff is going on.
That's where I think Material frontman kdocs kicks in.
So Material frontman kdocs is a theme for MKDocs.
It makes things a whole lot better, nicer to look at, just straight out of the box.
Very easy to use.
And it comes with a whole bunch of plugins and extensions.
So extra features that MKDocs cannot do by default.
So I see this as MKDocs with batteries included.
So this is actually how MKDocs should be out of the box.
Again, easy to install, use and configure.
All you need to do is in your Python virtual environment.
So I'll have to kill the serve here.
You do an pip install MKDocs Material.
So you just install an additional Python package,
which will bring in a whole bunch of extensions
and there's a whole lot of stuff going on here.
I'll serve this again.
Now, if I look at the website, nothing has changed yet
because I have to change the theme as well that's being used.
So in my MKDocs, I say theme, name, Material.
And as soon as I hit save on this and I switch back,
I think it needs a refresh.
Why is it not working?
Oh, something went wrong.
Ah, demos.
Okay, let's try restarting this.
Okay, I'm not sure what went wrong with the live preview.
Usually that works.
So this already looks a lot better.
So at least now I'm seeing my pages and the search.
The search here is amazing.
It's blazingly fast.
Even if you have pretty big documentation,
it highlights the things you can customize the search.
You can rank pages up or down.
If you want them to be more prominent in your search results,
there's a whole bunch of stuff you can do.
All right, so they get started with Material for MKDocs.
Just with pip install MKDocs Material.
You change your MKDocs YAML to use Material as a theme
and things start looking a lot better already.
And now the fun really starts because there's a whole bunch of plugins
and extensions you can start using as well.
Now, I'll do a quick cheat code here
because the MKDocs YAML I'll end up with is going to be pretty big
because I want to show you all the bells and whistles.
I'm not going to type all of that,
so I have a hidden file here
that I'm just going to move into the right place.
And we open this and you can see there's a whole bunch of stuff here going on now.
I'll explain it in the slides what's going on.
So one of the first things you can do is you can start playing with the colors.
You can change the accent colors.
So here I use like Fossdam purple.
That's very easy to change.
You just say, palette primary color should be purple.
The accent color, so that's when you hover over stuff, should be blue.
So it's very easy to play with the colors if you're interested.
But it's also very easy to do is introduce light and dark mode in your documentation.
So with a little bit more stuff in your MKDocs YAML,
you can say I actually have two color schemes.
I have a light mode and a dark mode.
The dark mode is called Slate for whatever reason.
The light mode is called Default.
Okay, now you know.
And what actually happens when you do that,
so here when I moved that big configuration file in place,
it actually already did a re-render and now I have dark mode here as well.
And it's actually a dark mode with tuned colors.
So I'm getting Fossdam colors in my website now as well.
So that's one small thing that's very easy to do.
Now let's show off some of the additional features.
Let me start a new page here.
Let's call it MaterialMD.
And let's start showing ContentTabs.
Material for MKDocs.
Save this, go back.
It should be picking up on that straight away.
Okay, so ContentTabs are a way of getting tabs
and like a subsection of your documentation page.
And the best way to show it is to really do the demo.
So I'll copy paste this markdown code in this one here
and I think it needs empty lines in between or it will not be happy.
Right, and now here I have tabs in my documentation.
So that's very nice if you say I need to show different examples
with C++ Python different code, for example,
this is a very nice way of doing it
because people can just pick what they're interested in.
You can also make sure that people can somehow give a preference,
like always show me the Python stuff.
And it will remember the first time they picked something
and throughout the whole page it will show always the Python example by default.
So it does some caching of this as well.
To enable this you need to enable two extensions, SuperFences.
So SuperFences is something where you can embed content into each other
so you can start with ContentTabs that then includes other stuff
and like it basically goes recursively so you want to enable that.
And then you do Tab and UltimateStyleTrue.
While it has to be true, I don't know, but fine, it works if you do it like this.
CodeBlocks is a very nice thing as well, also built into Material.
So let's show that off here.
We can do Code, Block with Python code and that looks very nice.
So this uses Pigments to do the syntax highlighting.
You tell it that it's Python here, so it doesn't figure that out by itself.
You have to tell it I could try rendering this as Shell
and it's probably going to look a bit funny.
Okay, so it looks reasonably okay.
So all of this works out of the box.
They don't have to install any additional stuff to make this work.
It knows about pretty much all the programming languages out there.
If you want to try Fortran here, it will probably still work.
Another very nice feature is what's called Admonitions,
which is a very strange word to me.
I'm not a native English speaker.
I'm not familiar with this term, but it's like nodes, warning tips.
So all of these kind of boxes you can include in your documentation
is called Admonitions in Material for MKDocs.
So a small demo of that is here.
Let's do Adma, whatever, nodes and stuff.
Again, it needs an empty line in between or it will not be happy.
And you start getting nodes.
You can use custom titles here.
So all the Admonitions have a particular type,
which mostly defines the color and the icon you get here,
and you can change that title here.
So you don't get the default.
The default would just be tip, I think.
So if I remove this, you'll see tip instead.
I think there's a more normal name for me.
Sorry?
Callouts, yeah, okay.
Fine.
Over naming you can always discuss.
I didn't pick the name, so don't blame me.
Blame Martin for that.
No, no, it's fine.
To me, it's a confusing name.
Another thing I really like and I know very much
that not everybody is a big fan of that is emojis.
You can use emojis in your documentation.
I think this is great.
It makes things a bit less serious, a bit less lighthearted.
You can have some fun in your documentation as well,
because some people think it's very boring to read documentation.
So for some people, this works.
There's emojis, there's icons as well,
so there's an arrow in here.
This arrow right is not really an emoji, it's an icon.
So this works pretty well as well.
Again, I want an empty line in between here.
So be careful if you have too many Belgian beers.
You may get sick in the morning.
All right, so this really works well for me.
And the documentation for Matilda from K-Docs,
there's a search engine here, so you can look for beer,
and it will give you all the options that you can use.
You can look for arrow, and if you click something,
it will copy, if you click in here,
it will copy paste it to your clipboard,
so you don't even have to type it over.
Really well done.
Over 10,000 icons, so you can probably find something
that you can use in there.
All right, another very cool feature,
which I haven't used myself very much, is using Mermaid.
So Mermaid is some kind of JavaScript tool to create diagrams.
So with a block of code like this, a block of mermaid code,
you can start including graphs in your documentation like this.
And these could be very complex.
They render very quickly,
and it not only supports diagrams like this,
but you can do pie charts, you can do UML diagrams,
you can do a Git branch workflow kind of stuff,
so this is very rich in terms of what it can do.
Again, you have to enable the corresponding stuff
in your markmkdocs.yaml, so you need super fences
with some custom fences and yada yada,
just copy paste this.
You start playing with diagrams in your docs.
You hit save, and if you're quick enough,
where is this site here?
You start having diagrams in your documentation as well.
So if you need this kind of stuff in there,
this to me beats putting pictures in there,
because here you can copy paste stuff as well, right,
from your diagrams, so this is better in many cases.
All right, I think I'm doing quite good on time.
The last big feature I should say that I want to highlight
is the block support.
So this is quite new in material for mkdocs.
It has been in the works for quite a while,
but now it's finally there in the open source version.
So this is something special,
a dedicated plugin for integrating a blog in your docs.
All you do is you do plugins enable blog, right,
and then you can start in a special structure here,
so you can do docs blog posts
and start creating markdown files in there.
Let me show you what happens if you do that.
So we want to exit here.
You want to make sure that the blog part is set up.
So this part is auto-created here by mkdocs.
As soon as you enable the blog's plugin,
it will create your landing page.
There's no post in here, of course.
So this is empty.
I can create a small markdown file here.
Let me check copy paste.
So here you can see this has a date.
This is basically the publication date.
So if you put this in the future, it will not show up yet
until that date hits.
I think so. I can try if that works.
So here blog.
This is our blog post that we just added,
and this has a dedicated page as well,
which here it's hard to tell,
but in the URL field,
it will actually use the date that you've put in the mkdocs as well.
So it's like everything is nicely date stamped and so on.
I think if I put this to a future date, it's not going to show it.
So let's try February 5th.
And now the post is...
Ah, okay, it's still here.
All right, fine.
But there is another way you can do draft through,
so I don't want to show this yet.
And then, at least on the landing page,
it should not be there.
So as long as it's a draft, it will not show it.
If you flip it to draft equals false,
or just remove that, it will come back.
Okay, so this is built in into material for mkdocs.
This is quite amazing.
All right, so lots of features.
There's lots of stuff I haven't showed.
It can do a whole lot more.
So please take a look at the documentation of material for mkdocs itself.
It's a very nice tool.
Another aspect I want to talk about very briefly is the way this is funded.
So funding is a very big issue for lots of open source projects.
And Martin here has come up with a way that works amazingly well,
and it's actually pretty simple.
So material for mkdocs is what's called sponsorware.
So there's an open source version of it available to anyone.
You just download it on GitHub.
You can pip install it, and you can start playing.
But there's actually a private version as well,
which has a couple more features already implemented,
but they are not available in the open source version yet.
To get access to this private version,
you have to become what's called an insider.
So you become an insider to the project
by doing some kind of monthly donation to the project.
And I think it starts as low as $15 per month,
so it's quite affordable.
You can also do a yearly donation if you're up for that.
And then what happens, you get access to all these new features
that are only available in the private version, in this insider version.
But eventually these features also come back to the open source version.
And that happens when a certain funding goal is being hit.
So Martin sets goals.
For example, I want to get $10,000 a month of income.
And then all the features that I list here
will become part of the public version.
So as soon as they hit that target, it works.
And this is nicely covered in the documentation here.
So on the documentation of material for MK docs,
you can see they're now getting over $13,000 a month,
which is quite a lot, right?
So Martin is actually building a team,
a development team route, material for MK docs, thanks to this funding.
So right now this is the funding level.
And he says as soon as we hit $16,000,
we will move all these implemented features from the insiders,
from the private version of the tool to the public version.
And then they stay in the public version forever.
So as soon as they hit this target, that works.
Now this is interesting because they've hit the $14,000 target already,
but then some sponsors dropped out,
and now they're back to a little bit below $14,000 again.
But that's fine.
Once it's public, it stays public.
What's amazing to me here is that the private version is just a private fork on GitHub.
So you get access to that private fork,
you get added to the fork essentially as a contributor,
so you can access that code.
But this model somehow works.
So you could say, okay, if I get the private version,
I could just give it to anyone, right?
And then it stops working.
But for some reason, that doesn't happen.
So it's like this honor system, like if you sponsor the project,
you get access to it.
And literally here at the bottom of the page,
it says, please don't distribute the source code that you get access to,
and apparently that works.
And they keep getting new sponsors over and over again.
They're hitting these goals every couple of months.
So that's maybe an idea for other open source projects as well to take a look at.
So yeah, Martin told me that this was a bit of a jump,
like a gamble, let's see what happens.
And it's been working amazingly for them.
So he's able to build a development team rather than just having to work on this himself.
Okay, a lot of features that I didn't cover,
which I'm not going to get into here, check the documentation.
One thing I do want to mention here,
it also makes it very easy to publish your documentation on GitHub pages or GitLab pages.
So it has an MK docs GitHub or GitHub pages something.
And if you integrate that in your GitHub actions workflow,
it will push it to GitHub pages and nicely integrate that in your GitHub account.
Yeah, that's all I have.
And hopefully there's time for a couple of questions.
Thanks.
Let's have a couple of questions and we'll see how fast they go.
First question.
Very quickly.
I have two of them.
Do you know if the icons, not much the emoji, but the admonition or whatever,
and also the charts, are they vectors or a roster?
So you're talking about these, right?
So the question is, are these vectors or are they bitmaps?
I'm not sure.
I think they're vectors, but I'm not entirely sure.
You could check, I guess, if you zoom in, where do I have that website open?
Here.
So if you zoom in, you can tell that these are probably vectors, right?
Yeah, right.
So they look pretty good.
The question is, if there is any kind of, maybe it's a stupid question,
but is there any kind of translation to this kind of documentation that I would say PDF?
Okay.
Is there a way to export the documentation into PDF?
I think there, the answer is no, but they're very much aware that this is a missing feature,
let's say, and that's something they want to work on.
I'm not entirely sure if that's correct, but I think that's what Martin told me.
Like, compared to other tools, there's like Docosaurus and there's Sphinx and there's other things.
Some of these tools can do a little bit more.
There's a plugin.
Yeah.
There's a plugin for PDF export.
Look, yeah.
So the plugin system in MKDocs is very nice.
Yeah.
Yes?
That's great.
Yeah.
One of the nice things about Sphinx in MKDoc is that you can easily do a code documentation
so you just send something into the documentation and grab the link.
You mean like generating API Docs or?
Yeah.
Yeah.
There's a plugin for that for MKDocs.
I didn't show it here.
I actually don't have it on the slides.
Okay.
I had it somewhere, but I think it's MKDocs.
Oh boy.
Doc strings.
Yeah.
So this is MKDoc strings.
That's the plugin you want to generate API documentation.
I'm using this in the Easy Build documentation, for example.
Works fine.
Yeah.
So the question is, did you run into issues with complexity because it's like tool or
another tool and when it talks, you know, maybe it's easy to contribute.
And yes, so knowing when to look if it's issue in the material or if it's underlying MKDocs
and how to do it.
So the question is, did you run into issues with complexity because it's a tool on top
of another tool and if something goes wrong, where's the problem?
Not really because usually if something goes wrong, you get like a Python crash and you
can tell whether it's in a particular plugin or in material or in MKDocs itself.
I haven't run into many issues like this, but if it happens, it's usually quite clear.
And if you don't know, you just report the issue to material for MKDocs and one of the
maintainers is going to tell you it's not an issue here, it's an issue there, you should
report it there.
And you say one thing on top of another, that's not entirely tool, it's like plugins.
So they do like integrate with each other and there's some complexity there, but yeah,
usually it's quite clear if you get like a Python crash, you can tell from where it's
coming from.
Can I stop here?
Yeah.
Thank you very much.
Okay.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.
Thank you.