Introduction posts

[pawamoy]

Here you can post a comment (as a new thread) to introduce yourself. Some things you can share with us:

• your interest in MkDocs and the ecosystem
• your background, skills or domain expertise: super useful to know who can help on different tasks 🙂
• plugins you maintain? always nice to associate plugins and their authors 🚀

[EddyLuten]

Hi folks! I'm Eddy, creator of mkdocs-alias-plugin, mkdocs-categories-plugin, and mkdocs-live-edit-plugin.

I work as an engineering manager for a medtech startup, and before that, I worked as a software engineer of some variety for various companies in the Bay Area. I use MkDocs for my personal projects, though I'd love to find a decent excuse to use it at work as well.

Though most of my time is taken up by personal projects, my goal for further MkDocs development is to create plugins to develop personal KBs and create more deeply connected pages through relationships. I currently use Obsidian for note-taking, which is a shame, considering how much time I've put into MkDocs plugins.

[d0ugal]

Hey everyone, I'm Dougal and my claim to fame is having the most commits in MkDocs (but I see that will be taken from me soon!) I joined very early and took @tomchristie's early work that he extracted from another Django REST Framework and helped make it work more robustly for general use cases.

These days I'm not active but still enjoy the project.

I'm a backend Python and Go dev. I have done a bunch of open source - working at Red Hat, Canonical and others. Currently working at Grafana Labs.

[tomchristie]

I'm not sure anyone's gonna be able to beat your numbers @d0ugal...

still lookin sharp, dude. 🔥

[d0ugal]

Once I find some more code to delete I'll be back! 😉

[tomchristie]

Hey team, I'm Tom and my claim to fame is starting this darned thing way back in internet pre-history times.

📝 Seriously, like ten years ago. Ye gads.
👨🏻‍🎤 I clearly thought it was pretty kickass at the time, and I think it's still awesome now.
🧐 Although I'm older and somewhat more serious these days.
🖥️ I seem to work on Python open-source projects quite a lot.

[unverbuggt]

Hello,

you can call me René or unverbuggt. I'm an electrical engineer and a plc (programmable logic controller) developer at my job. I stumbled across mkdocs during the pandemic in 2020 while looking for an easy way to build a webpage for an upcoming event without wanting to install a complex CMS. And, I was amazed by the beautiful results of firing a python script over markdown files and a small configuration file.

That's when I also found and first used the mkdocs-encryptcontent-plugin. It blew my mind being able to upload a webpage to the internet with secret content (e.g. a members area), that not even my webhoster (or the police) could read. I believe this was an usp during that time.
I also started building my own theme for my projects (e.g. my not jet open sourced tools collection at epwg.de), because I wanted to learn and understand how current web development works, without using hundreds of dependencies of different huge frameworks. But probably nobody uses it besides me, which is fine (I also got feedback from co-workers that the color combinations are pretty ugly). I also diverted mkdocs a bit from its intended use for a family-tree project.

I started collaborating at the encryptcontent plugin. First by opening issues and discussing possible solutions, then by suggesting code changes (without the curage to start a fork and opening pull requests). In the end of 2022 the developer of the plugin CoinK0in wanted to abandon the project, because he lost interest. Being the last one he was involved with in the project, he asked me if I wanted to continue it and I said yes. I then began fixing bugs and refactoring and also implementing new features up to the release of version3 late in 2023. I have some ideas on new features of the plugin but currently other things in mind, so I focus on fixing bugs.

So here, one part of me wants to get early information of upcoming changes that impact or break my plugins and the other part wants to fix problems and add features like:

• the long build/serve time when big files (like videos) need to be copied every time
• auto-building on file changes and then uploading to a webserver (e.g. being able to edit the markdown files on a nexcloud share and automatically building/uploading)
• extending the documentation with a collection of some neat configuration or scripting hacks
• tbd

[byrnereese]

My name is Byrne Reese. I live in Oakland, CA and work at a cloud communications company called RingCentral. Before that I was Head of Education and Developer Content Strategy at Roblox, Head of Product at Uphold (a crypto company), Head of Customer Development at Toy Talk (later Pullstring), and the list goes on. I started my career as a software engineer, became a product manager, and worked at countless startups until settling in at RingCentral most recently.

I was introduced to mkdocs through my role at RingCentral where my predecessor began using it for some simple documentation micro-sites for the company. I fell in love primarily with it being a markdown-centric documentation system. I love markdown, and love the simplicity of generating a site using mkdocs.

I started to expand our usage of mkdocs internally, and migrated all of our developer guides and documentation to mkdocs. At the same time, I started to develop plugins and themes in support of our documentation projects, including:

• https://github.com/byrnereese/mkdocs-git-committers-plugin
• https://github.com/byrnereese/mkdocs-swagger-ui
• https://github.com/byrnereese/mkdocs-markdown-filter
• https://github.com/byrnereese/mkdocs-minify-plugin
• https://github.com/byrnereese/mkdocs-moonstone
• https://github.com/byrnereese/mkdocs-ringcentral
• https://github.com/byrnereese/mkdocs-ringcentral-api-index

Don't judge my code. I am a glorified hacker at best -- knowing just enough to be dangerous and to solve my immediate problem. :)

Here are some sites I have authored using mkdocs:

• https://developers.ringcentral.com/guide
• https://ringcentral.github.io/rc-unified-crm-extension/
• https://ringcentral.github.io/ringcentral-embeddable/

Earlier in my career I was an active champion for open source and open standards. I was in the AtomPub IETF working group, contributed to the invention of OpenID with Brad Fitzpatrick, and led efforts across many different companies to adopt open source and to open source their projects for others to benefit from. As I got older and my family grew, I had less time to participate in the ways I once did so freely.

Mkdocs though is a project I find I have a large passion for. As someone who has spent their career writing developer documentation, and shaping developer experiences, mkdocs is a tool I gravitate towards for its ease of use, simplicity... and power.

I am here because I want to begin contributing once again more directly to the projects and products I value and enjoy using.

[fralau]

My name is Laurent Franceschetti and I live in Switzerland. I have been an independent operational consultant in the banking industry for a couple of decades. I had started my career working for a Software company in banking telecommunications, writing user manuals and training users.

For those who remember Antiquity (or who have read history books), I started my career in the early 1990s on VAX machines, in the Golden Age of VT terminals and Vax Document, when Humans used to rub elbows with the Gods. With Vax Document, we had it all: markup languange, superb typesetting, beautiful graphics, LaTeX/Postscript, and soon pdf and HTML. Just see for yourself, if you don't believe me. That mythical Atlantis collapsed under the ocean, when Microsoft Word publishing was introduced on Windows machines (and then Digital Equipment Corporation was sold to Compaq and summarily executed). I lived ever since in mourning 😢.

Wikis gave me some hope, but the WikiPatterns renaissance was messy and shortlived, killed by infight between markup variants, as well as competing wiki engines: it kind of went mainstream but faded into the background.

And then came Markdown by Daring Fireball... Finally we had agreed on a common language.

In the mid-2010s, I attempted to create a replacement of VaxDocument that would start from Markdown and used Python and pandoc to produce LaTeX. I called it... MakeDoc, of all names. It worked, too, producing impeccably typeset manuals and marketing brochures again; but the code was messy. Then I took the whole thing from scratch and created a second version, that used Jinja2. It was slightly better, and even processed Word documents (far better than Pandoc does). I hoped to start some kind of Revolution, where the needle of publishing would be finally unstuck from MS Word and set back to the middle of the dial. OK, I should throw most of my code away and try a third time, but I haven't gottent around to that yet.

And then I came across MkDocs! Not the same purpose, really (it aims at making static sites, not typeset documents). But still, there was a lot in common in our respective approaches.

I contributed with two plugins:

1. The first thing I did, quite logically, was to bring wiki macros to static websites made with MkDocs, since that was lacking; this led me to the creation of the plugin Mkdocs-Macros; minus the pain in the neck that writing macros was on wikis. In a dreamlike fashion, there is something of the PHP framework in the way I tried to build up a consistent, document, batteries-included environment (as I mentioned elsewhere, there was also a little bit of Don Knuth's literate-programming philosophy). For once, the result is not too bad and I do not have an urge to throw it away. I hoped that it might have some niche appreciation, but didn't expect adoption by so many websites! 🙏 And to be graced by an invitation to the core sanctuary 🙇‍♂️ .
2. As a side thing, I like the Mermaid diagram language 👍 (and hate diagram software 👎 ), so I wanted to make it easy for anyone to insert Mermaid diagrams into an Mkdocs Website: hence the plugin Mkdocs-Mermaid2. It started as something simple (reviving an unmaintained plugin); but as usual, it tended to complexify under the hood, to follow the evolution of the Mermaid library (cool stuff).

I would be happy to know how I can contribute to the core of MkDocs. For the moment, I am quite happy with MkDocs as it is, with some aspirations for the future but little demands on a day-to-day basis. But if I could give my feedback, or contribute something to the core (within the limits of my skill), I would be happy. Usually what I do best is to document knowledge and best practices, because writing is both my hobby and my daily work...

[pawamoy]

Hey everyone, I'm Timothée, you can call me Tim 🙂

I ended up learning maths and computer science in college because I had a great math teacher in high school ❤️ Maths became super complicated and I wasn't able to follow, so in second year I opted for full computer science. When I first saw "Ubuntu" I was like "what is this stuff lol" (coming from Windows the annoying operating system...) 🫣 But I quickly saw how powerful the shell was, and started writing tons of scripts to automate many different things.

At some point I got an internship, that became a full-time job, where I used Python and Django to build a website (full-stack role). I also worked on my open source projects on the side. After a few years (~7) working for others, I took the leap and quit my job to work full-time on my own projects, setting up a sponsorware strategy very much inspired by what Martin did with Material for MkDocs.

Today I maintain several MkDocs-related projects, like mkdocstrings, mkdocs-autorefs, mkdocs-manpage, mkdocs-spellcheck, markdown-exec, mardown-pycon, but also developer tooling like git-changelog and duty (see the whole list on my profile).

I don't have any particular skill, just a lot of practice with programming and shell/Python development. Doing my best in every aspect of maintaining open-source tools and libraries 😄

[ojacques]

mkdocs-spellcheck is actually at https://github.com/pawamoy/mkdocs-spellcheck (also incorrect link on your profile 😃 ). Great stuff!

[pawamoy]

Oh, good catch, thanks, will fix it 🙂

[smarie]

Hi there, I am Sylvain, a few things about me:

• I spent the past 18 years in the energy efficiency industry, first on embedded software (OSGi) and plug'n play network protocols (DPWS/WSD...ugly SOAP :) ), then a little parenthesis on business intelligence/datawarehousing on IoT data, and finally on AI/Machine Learning for IoT timeseries
• I have way too many open source projects open in parallel and am not able to bring all of them to "industrial" quality standards, but I remain quite happy when some of them are used and help developers spend less time on boring stuff - and having more fun in general.
• I also enjoy research and lately have been trying to spend more time writing papers - which explains my interest in mkdocs-bibtex
• We are using sphinx in my company but I love mkdocs' simplicity, therefore I created mkdocs-gallery, and am very happy to see mkdocs-mermaid2 too :)

As a non-UI expert I will be a mere "follower" here, just happy if I find time, to validate that disruptive changes are ok with mkdocs-gallery.

[timvink]

Hi all, My name is Tim Vink. I live in the Netherlands, in a city called Haarlem. Most of our country is very flat and below sea level, but Haarlem is 2 meters above sea level, so I basically live safely on a hill :)

I have been building machine learning models for large corporates for more than 10 years, of which the last 5 or so managing ML teams. I first stumbled onto mkdocs when looking for a documentation-as-code solution. For important ML models, the requirements for documentation and validation procedures (by external validation teams) are still increasing. We needed to automate it more.

Like the others above, I kinda fell in love with the simplicity of markdown + configuration file = beautiful static website. I build a range of plugins solving problems we hit as a team using it to document our machine learning projects and our internal tools.

• mkdocs-git-revision-date-localized-plugin
• mkdocs-git-authors-plugin-plugin
• mkdocs-table-reader-plugin
• mkdocs-print-site-plugin
• mkdocs-enumerate-headings-plugin
• mkdocs-charts-plugin

I have really enjoyed the interaction with other contributors improving the plugins further. The most used plugin mkdocs-git-revision-date-localized-plugin has 23 contributors! I've learned a lot in the process. One thing I came to appreciate is the amount of edge cases you need handle even for simple plugins.. building robust software is hard.

Here because I'm excited about making mkdocs even better and easier to use.

[koaning]

Hi, I'm Vincent.

I maintain a little site called calmcode.io in my spare time and one of my first courses there was about mkdocs. It is really due for an update because it's been four years ... but eager to work on that.

I haven't been that active with the mkdocs plugins, but one plugin that I made via calmcode has managed to get somewhat popular none-the-less: mktestdocs. The project could use some more love, it's important that codeblocks on documentation pages are properly tested.

I'm very interested in creating interactive widgets for documentation pages, which is a big reason for me to hang out there. You might wonder what I mean by that, so I figured I'd add two videos that help explain it a bit.

CleanShot.2024-04-11.at.21.09.18.mp4

CleanShot.2024-04-11.at.21.08.34.mp4

[pawamoy]

Oh wow. Interactive widgets are what I get the most fun from. I'd love to learn more about the ones you show in these recordings, and how they work. I have a project in alpha status that is meant to display a recorded code execution, where data packets flow within a call graph. Very interested in potential technical solutions for this.

[koaning]

I think the most general thing I can work on is something that you can just insert as if it's a plain old html element without the need of npm. That way it fits in markdown, and most doc pages.

For the first visual that might hopefully look something like this someday:

<contextimg src="path/to/img.png">
    <context label="a" x="20%" y="30%">
        <p>This what you'd see when you hover over label "a".</p>
    </context>
    <context label="b" x="50%" y="30%">
        <p>This what you'd see when you hover over label "b".</p>
    </context>
</contextimg>

I can totally see a bunch of images on doc pages that would benefit from a context hover element. Especially in ML architectures where the order of operations can really matter.

[koaning]

It's safe to say that the scope of this is a bit beyond mkdocs, but I'm hopeful that such elements can greatly enhance mkdocs projects nonetheless.

[ojacques]

👋 I'm Olivier.

I currently work at AWS as a DevOps and Cloud architect. I live in France, fly my paraglider 🪂 in the Alps and play in a music band. You can read this on my own README.md, yes - an mkdocs site.

I am so humble to join this discussion and effort, as I consider all of the contributors here as my heroes.

Regarding mkdocs, I came to it as I have a passion for everything-as-code (not just apps and Cloud Infrastructure). I am convinced that documentation (at least, technical documentation) must be engineered, and managed "as code" too. That we must follow developer-like discipline which includes automated testing (CI pipelines), thorough and traceable collaboration (merge/pull requests), DRY (don't repeat yourself, thanks to macros/includes), and deployment in various shapes of forms with CD pipelines (web sites, but also PDF, DOCX, or even Wikis such as Confluence). Write once, use many times.

mkdocs is my way to do documentation-as-code, and embark others, to exemplify the "everything-is-code" culture.

Few more things about me and mkdocs :

• I am the maintainer of mkdocs-git-committers-plugin-2, a fork from the original mkdocs-git-committers-plugin from @byrnereese. I needed more capabilities, including GitHub Enterprise and GitLab support. We never came down to merge the two, but it is still in my todo :) . I use the plugin to foster contributions to the documentation, directly from the readers of the doc. Who else is better positioned to point out improvements or issues on a doc? The readers! Adding a link to the profiles of the contributors of a page is a very powerful way to encourage contributions.
• I have another fork of a plugin to publish mkdocs pages to Atlassian Confluence. I like to have one source of truth - mkdocs in a Git repo, and when client requires to publish documentation to Confluence, this is just another step in the CD pipeline
• I submitted (with other AWS employees) mkdocs-material for sponsorship from AWS Open Source Software Fund and it worked 🥳. This was important to me, as AWS is an important user of mkdocs and mkdocs-material.
• I see many additional opportunities in integrating documentation as code (hosted through mkdocs) for additional usages, such as GenAI/LLM (search of course comes to mind, but also summaries, automatic diagram explanations for persons with disabilities, automated / high quality translations, different writing styles (like strict, elaborate, summarized, or even adding humor)). Diagram-as-code is still an area which could use some more improvements (mermaid is lacking features, D2 looks promising yet a bit hard for some usages), and drawio integrated in VSCode is nice but not really "as code" (like mermaid).

The original mkdocs authors, the latest maintainers, and the plugin community turned mkdocs into a de-facto standard for tech docs. This is impressive.

One last thing:

• I miss an mkdocs conference!

[byrnereese]

I came to it as I have a passion for everything-as-code (not just apps and Cloud Infrastructure). I am convinced that documentation (at least, technical documentation) must be engineered, and managed "as code" too.

I love this and agree. I like reading these little testimonials, as it is helping to highlight the values underpinning this project. We all come to this project for a reason - and I bet we will find a lot of camaraderie amongst our users on these values. I can see this fitting into a new mkdocs landing page and website!

[byrnereese]

Do you think we can create opportunities for us to have a booth at Amazon Re:Invent, or to present to developers on this project? It would be great if Amazon/AWS could help sponsor this project in that way.

[tomchristie]

I miss an mkdocs conference!

https://www.writethedocs.org 👈

[ultrabug]

Heya, I'm Alexys 👋

I live in Paris, France 🥖 and work as CTO for Numberly. Through my work, most of my attention is drawn to projects and databases used to build distributed systems for some kind of data processing.

I've been around OSS for a while now as a contributor, author and love to share what I learn in conferences.

I came across MkDocs thanks to a colleague of mine when I wanted to get rid of Wordpress and switch my site/blog to a statically generated site. Since we French like to translate things to our language, I was surprised that MkDocs didn't provide anything to do so at the time.

With the help and patience of Waylan, I ended up contributing i18n support for built-in themes and I created the mkdocs-static-i18n plugin to hopefully allow the MkDocs ecosystem to localize their documentation and spread the MkDocs love and know-how via blog posts and conference talks 😉

I'm happy to stick around and do my best to help bring more MkDocs content to everyone 👍