 And Let's welcome Alexis Jacob Hello. Hello Yes, you sound perfect you're the CTO of Numbally and Can be found on the internet just as a warning ahead as ultra bug. So that's an interesting name Yeah, but I don't want to break your concentration now because you're going to tell something about static documentation Yeah, and so let's start your screen share now and I'll leave the stage to you Thank you very much, Martin. Hello, everyone. I'm very pleased to be with you today. And yeah As Martin said, I'm the person between standing between you and the lunch break. So I Promise I'll be on time. I'm today I'm going to explain and demonstrate how to generate static documentation or website that supports multiple language using mkdocs and github When I switched my own website from WordPress to mkdocs I wanted to support multiple languages of it, but I found nothing but ancient mkdocs issues asking for it and you'll be surprised to know that This feature has been reached by the mkdocs community since 2015 and I hope that this talk will equivalently surprise you In demonstrating how simple we've made it to achieve in 2021 I'm super happy to have worked in making this a reality for the community So let's start as you can already judge by my accent. I'm French I'm from Paris My name is Alexi. I'm CTO at Numberly just like Martin said So you spoiled it a bit for me, Martin I'm engaged with mostly Python based project and communities and PSF contributing members as such. I'm the author of various open source projects Such as one that I will be talking about today I'm an mkdocs contributor and maintainer as well. All this work made me a maintainer of mkdocs Maybe I got a bit too much involved there I've been a gen 2 Linux developer as well for more than 10 years now Where I work on packaging cluster or distributed databases Related stuff and I'm also part of the people that are maintaining the gen 2 Docker containers. I like to share my Experience and production experience during tech conferences such as Europe Python for many years now With tech webinars blog posts on my on my website that is linked below And yes, just like Martin said you can find me about everywhere as a trouble So let's start by introducing the different components that we'll be using to achieve our goal today And the first one is obviously related to the documentation engine which Is mkdocs that is that has been created in 2014 by Tom Christie? The idea is using a very simple email file to configure your site mkdocs will generate a static Site out of plain text files Formatted using the lightweight markup language called markdown Speed and simplicity where the key drivers of the mkdocs development and that explain I think why it became so popular mkdocs Read is written in Python the core itself though You don't have to use any Python at all if you want to use it but I'm just saying this because it's source code is really easy to understand and we are open to Contributions so feel free to look into it if you want to I've put on I've put down some links to some markdown guides and Tutorials if you want to to to learn more about the markdown markup language Then mkdocs sites can be teamed and while it comes with two built-in teams Their look and feel is a bit dated and their customization is limited mkdocs material is by far the most popular team for mkdocs as it is based on applying the material design principles to mkdocs generated sites It is very customizable searchable mobile friendly supports Multiple languages also And in case you didn't know material is an open source design system from Google That helps teams build high quality digital experiences It defines guidelines layouts colors Typography and components for teaming websites mobile applications and more So I've put on the link as well if you want to to check it out now, let's talk about supporting multiple language of our documentation or website and Supporting multiple languages is a is called Internet is it internationalization or localization or Actually depends who you ask and before bringing multiple languages support to mkdocs I must confess that I never gave a thought about this So I was I was quite amazed to see how this question could generate in degenerate in a in a flame war I don't even know how to pronounce those I 18 N or L 10 N acronyms. I think you just write them down to be honest What I learned along the way is that the 18 in I 18 n stands for the number of letters between the first and I and the last n in the world internationalization and the same goes for the Internationalization and that's where the L 10 n come from So as a disclaimer choose your side at your own risk. I will just explain our reasoning for mkdocs Please do not shoot the messenger. I even put a nice kitten on the slide to to increase my chance of survival Anyway, after debating this question, we agreed that the core feature That we were developing to allow users to localize their content should be called Internationalization and it took me two months of work and 175 commits comments, sorry to get the feature into mkdocs not to agree on on the internalization term don't worry and now in mkdocs internalization feature applies to It's it's important to note that it applies only to team Translatable texts such as the search dialogues not not the documentation Content or website actual content though it could be extended further because since it's based on Babel if you wish to But to translate the actual content text of of the documentation you need the Mkdocs static internalization plug-in. I wrote this plug-in in the same spirit of Mkdocs it aims at making the translation of your documentation and website as fast and simple as possible I hope that by the end of the talk. I will have convinced you of this statement The idea is that you create a static and localized version of any file in your project Be it markdown pages or even images and assets And the plug-in will generate a version of your documentation site for every language you define and localized The local is the look like the localized version of your documentation will be made available using a slash suffix on your url Pass but I will detail and demonstrate everything everything soon anyway I was happy that it quickly got adopted by a few Cool projects such as a spaceship prompt and the bus is using it as well for their copilot CLI documentation now Let's get to the hosting side side of our site and It will be github and github offers the github pages Feature to build and host static project sites directly from a github repository This is very convenient and very powerful when combined with the simplicity of mkdox so you get one site for your github account organization and for every repository or project you have you will get a Website url for you with HTTPS and you can even set your own custom domains on it It's very very useful. There are of course some limitations but I think they are high and a good match for the kind of static website we're talking about and Of course, you should not abuse github's goodwill and try to host dynamic business powering websites Using github pages because why while you will get a gentle message from them if you exceed the soft limits They might not be so gentle if they feel abused Okay, now that love is in the air. Let's get started Everything I'm going to show you is part of the github repository listed here The repository contains a branch for every step that I will be taking and demonstrating afterwards So we'll need a clone or a fork of it Then we need to set up a virtual environment created as shown Of course, Python 2 is out of the scope and not supported by mkdox anymore The rest of the presentation includes github video captures of every step taken just like a live demonstration But if you want to follow along and try it yourself during the talk be my guest On the top right corner of the following slides, a recap image will be there with everything you need to catch up So don't freak out if you missed a step and have fun Also a web version of the presentation is available on my website, including the demo gives, etc. So you can always find your way through afterwards without having to look at YouTube or pdf You have it all Let's get down to the requirements Obviously, we need mkdox. We recently released version one two two So I'm basing this talk on the last version at this time We won't need the actual internalization option of mkdox itself since we will not be using the default teams We will be using mkdox material, which comes with its own support for dialogues and elements localization Then we obviously need mkdox static internalization plugin to allow us to localize and translate the actual content that we are going to talk about Let's look at the steps that we are going to take to get our localized mkdox project site live on the internet Thanks to GitHub pages I'll be detailing every step, but let me run it down for you now First thing we are going to do is initialize our project using the mkdox new command Then we will build and serve the site locally so we can preview it and in our own browser And for this we are going to use the mkdox serve command Then we are going to start modifying the content, adding assets and localize our website And while we do this, the mkdox serve will detect the changes and reload our local version and preview of the website immediately So we will be able to actually see the result of our changes live When we will be done, we will commit and push the changes to the GitHub repo And then we will deploy our site to GitHub pages using the mkdox GitHub deploy command And that's all, our localized website will be online Now let's start We initialize our mkdox project, we use the mkdox new dot inside the repository It will create two files, the first one is mkdox yaml configuration file And then it will create a folder with an initial index.markdown file that will serve as our own page You can see that on the little images thumbnails, I will highlight the things that are important to see in red So here we see that using this command, it created the two files Great Now we are going to testing and previewing is very handy and comfortable when working on a website project So mkdox serve gives us what you see is what you get feeling that we are looking for So it will build, run a local server so you can open the given URL on the port 8000 And your browser will display the rendering of the index.markdown that was created in the step before So you will get presented the default mkdox website in your browser Now let's demonstrate how live reload works by changing the site name So here you see that we have the file directory structure that I just explained I'm going to run mkdox serve My website is ready, you see that the name is highlighted Then I'm going to change on the mkdox yaml configuration file When I write and save this file, the mkdox serve will pick up the change and automatically reload And you can see that the title in our browser has just changed It's as simple as that Change detection applies to both the mkdox yaml configuration file and all the files in the docs folder Now let's switch to the default odd looking mkdox team to the nice material team So I run again mkdox serve and then I'm going to change the mkdox yaml configuration file I'm going to write team, name, material and I'm just going to save this And once again the build will pick up, it will rebuild and switch to the team, the material team Which is very and better looking as you can see Two lines in the mkdox yaml configuration file and we are done Let's go one step further Now since material is highly calculated, I'm going to change the name Let's go one step further Now since material is highly customizable, we want to switch the color of our website to europeiton's green color So I'm going to run mkdox serve and then now I'm going to change the palette, primary, switch to green Once again, I saved the mkdox yaml file and our website just changed to green Once again, two lines Cool Now we want to add an image asset and display the europeiton logo on our home page So for this, I created the assets folder, I put the png of the europeiton logo in it as you can see And then I'm going to modify this time the index.markdown file And add a reference and ask to display the image So I write down europeiton21logo.png I'm going to save this, of course And then I'm going to run mkdox serve so that it builds and refresh my browser And when I do, you will see that the image appears in our website So we just put up an image asset now in our home page Cool Now let's start localizing our content We know how to change the team, we know how to add an asset It was fairly easy and now we want to translate the actual content And here comes mkdox static internalization plugin This plugin will create, as I said, the slash language version path at the end of your website URL For each language you configure, it requires a default language And a list of all the languages you need, a version of your site with their display name So here, for example, in the configuration, we list the EN and FR languages So English and French languages And we configure the EN language and English as the default version It means that the default URL will be English If you go on your website, the root slash will be the English version If you add the slash EN site to your URL path, you will also get the English version So they will be the same actually But if you switch to the slash FR path, you will be on the French version of the website What is also very cool is that the plugin will take care of configuring a few things automatically for us And it will be very handy The first thing that it will configure is the search plugin It will make sure that the search plugin builds its search index in a localized way as well So when you are on the French slash FR version of the website And you start looking and searching for something, you will get the French result And not the English one So it contextualized the search for you It will also adapt automatically the material theme language So if you're using material theme, it will switch on the slash FR French version And you will get the French dialogues of the material theme And it will also configure the material theme language switcher It will have this language switcher in the header of the website So you can easily switch between English and French Now it's time to work and translate our website content So the way it works is that the mCadox static internalization plugin Detects the localized version of any file from their language suffix and extension So we localized the version of pages and assets by to fixing them with dot language dot the extension of what you're doing So in our case, we want to localize the home page So the home page was index.md So we are going to rename this index.md to index.en.md Since it's the default and English language And then we are going to add another file index.fr.md for the French version You can see it as well on the directory highlighted It will look like this In the English version, you get what we had before, EuroPython 2021 home page And everything is written in English, obviously And you do the counterpart in French If you don't know French, believe me, it's French Index.fr, this time dot md And that's all there is to it So let's demonstrate it live So we had this website So I'm going to show you that in the directory structure now Instead of having index.md, I have index.en.md And the French one as well And now I'm going to start configuring the plugin I'm going to ask for the search plugin I'm going to load the internalization plugin Set the default language to English And then define the languages I want a version for English will be named English And fr will be named French I write this mkdox yaml configuration file And then I just run mkdox serve And here you can see that Immediately the page has been refreshed I see my title and then I see the language switcher That has been configured for me If I go on the English version I see this If I go on the slash en I still see the same as the default version Since they are both English Now if I switch to French I see the actual content of the French I see the dialogues of the team has been switched as well To the French language So everything was done automatically for me By the static plugin That's all But now let's go one step further What if I wanted to localize the assets In the documentation site In the French markdown source of an image We would have to reference the French version Of the image And the same goes for internal page links French pages would need to link and reference French suffixed versions of our pages This would make translating content slower And cumbersome even more When we add or remove new links and assets Any page would need to be updated specifically But fear not The mkdocs static internalization plugin Will automatically use the localized version Of any page or assets Referenced in your markdown source Without the need of their .language suffix So the way it works is That if we take back our example here We have the index.en.md and fr.md They both refer to the same EuroPython logo png Without its extension Even though on our directory 3 We have created an English version of the Image of the logo And a French version one The plugin will detect that When we are on the slash or slash en version We actually want the .en.png version Of the logo And when we will be browsing the slash fr version Of the documentation We actually want to see the .fr.png But in the source itself Of the markdown pages We reference the image without Its localized language extension It will be localized automatically So we can actually focus on translating The text and not juggling Between the assets Or page link references We just reference them without it So let's demonstrate this live So if I look at my directory 3 In our repository What we can see is I have An English version and a French version Of the logo If I look at the source of the markdown The English version of the markdown I can see that I do not have The .en.png reference And if I look at the French one I just have their non localized version Now if I do mcadox serve It will build this Reload the version on the website On our browser And as you can see I'm on the default Meaning English version And I see the English version of the logo If I go on the slash en Since it's the same I still see the English version of the logo But if I now switch to the French version I see the French version of the logo That's it And we have successfully created a website Supporting multiple languages using mcadox Plus it has automatically configured And localized the reference of our assets So it's even easier to do It has a great look and feel An intuitive ergonomy And a cool and localized search engine It's time we pushed our great work To our repository So we just add the files that we created We commit them nicely And we push them to our GitHub repository Once we are done We want to deploy it So that GitHub pages starts hosting the build site So for this we use the mcadox GitHub deploy command Which will go through multiple steps The first one is to actually build Our multi-language website As you can see it builds And then it says building en documentation And then the fr documentation When it's done The result of a build process Is to create a site folder Containing all the static elements of our website And it will copy the site folder To the GitHub pages branch Once it's done It's going to push the GitHub pages branch to GitHub That's all And that's even more all Because GitHub pages will see that And will automatically configure itself So you don't even have to configure GitHub pages Or go to your repository or anything As you can see The source will be the branch GitHub pages You will get a mural immediately set up for you And with HTTPS Well done Our multi-language mcadox website Is online and hosted by GitHub You can check it out yourself On the given URL And at this time I know how you feel You feel that it was really too easy So let me try to make it a bit more complicated now Maybe Let's say that we want to make A GitHub build And update our website automatically Whenever we push new changes to the main branch For this we need to create a .github Slash workflows Slash GitHub deploy YAML file And configure it as shown What it says is that When we push to branch main Execute those jobs There is actually one job, it's a build Between inside the job there are different steps The first step is to check out the repository We are going to set up a Python version We are going to install the requirements Just like we did before on our own virtual environment And then we are going to instruct GitHub actions To actually execute mcadox GitHub deploy for us That's all And now any push we make to the main branch Will trigger GitHub action steps Which we run the mcadox GitHub deploy command for us Triggering a refresh of GitHub pages And update our website automatically So I'm sorry, I think I just made everything even more easier than before I just need one file Let's get down to some resources now that can be useful to you The first one is In case you didn't know There is a mcadox as a wiki on GitHub Where all the plugins are listed It's community-based So anyone can add their own plugin there So if you look for a plugin, a specific thing Start there And then I wanted to highlight three of the plugins that I use And find very interesting The first one is applying to handle URL redirections So if you want to redirect a special URL to a specific part of your website You can using this plugin The second one is very useful When you want to be able to control the navigation ordering of your pages And even more inside the structure of your page Of your website So you can have different styles of ordering Because if you don't have this They are sort of alphabetically So what if you want reverse What if you want this one first And then alphabetically Or this one first and this one first And then the rest reverse alphabetically It's very very convenient and handy Check this one out as well And the last one is very interesting as well Because it allows you to hook your own functions to the build process So when you build or GitHub deploy or whatever You can hook a function that you have defined inside your code To run That allows you to, for instance, create dynamic pages That you want included And you want those pages to be dynamically generated by a function Without having to create your own plugin or whatever So that's pretty interesting Because every time you build it will be reloaded Very nice little and simple plugin On the markdown extensions side Because markdown is extendable There are a few ones that I wanted to highlight The first one is attribute list This one is cool because it allows you to add brackets After let's say an image reference To add some CSS to it So what if you want this image to look round And of a certain width You can do it using the attribute list markdown extension Directly in your markdown And the second one is called admonition I don't know why it's called like this But maybe you do It will allow you to create nice little boxes Like you see and like I have displayed here So when you want to display nice and good looking disclaimer Note or whatever You can do it like this using the admonition It allows you to quickly add it to your markdown source And it renders very nicely The third one is a table of content Permalic generator Which add anchors and autolinks To the different elements of your table of content It's very handy Of course no website today Can be a full website And a real website without nice emojis So you can have it as well here And the last one is interesting as well Since it allows you to have a nice task list With good looking check boxes So if you're into this Check it out as well Those extensions I have showcased as well In the repository that I told you about earlier So if you switch to the extensions branch You can see a demonstration of how they are used So this can be convenient for you If you want to test them out easily So check it out there That's all for me Thank you very much for attending You can find me about everywhere as ultra bug as I told you earlier The repository of this talk is linked here The web version as well Check them out I've made a lot of efforts to make them easy to use And to understand And I wanted also to take the opportunity To extend a special thank you to the contributors And to the people that have interacted with quite a lot During all the work process And open source and contribution process To make all that I presented to you today Available and as easy as it is today So thank you very much for attending Have a very very nice Europe item 2021 Okay, so thank you very much for this introduction And also for providing both the slides And the GitHub repository So that we can try out all this on our own We had quite a few questions And let's do a simple one first And that's from Sebastian Oh sorry, I missed, well Is it possible to use doc strings from the code To generate some docs automatically? And while we were discussing this Gina was also getting involved in this And she looked it up and had a more specific questions Like do you have experience with something like MK Autodoc to generate API docs and MK doc? So the answer to Gina is No I don't have experience with it Anything that generates markdown Should be anywhere readable and usable Even more when they are hooked With the plugin that I showed earlier Which can make generating things very easy So I don't know also about the doc string part This is pretty usually very common in Sphinx Of course, I'm sure there are tons of things Because NK docs has very widely penetrated The documentation, hosting and generation Of a lot of projects and most likely Python projects of course So I'm sure there are a lot of things to check out I guess you get this kind of answer In the MK docs wiki page Where a lot of things have been discussed And are shared There is also GitHub discussions on MK docs Where you can ask your questions And I'm sure that those questions Have already have an answer waiting for you Yeah, thanks for that You've showed this with GitHub And Dragos asks Does it also work with GitLab or competing Git? I know that on GitLab it should Though you don't have the MK docs GitLab deploy command Bitbucket I don't know I don't know at all because I've never used it To be honest But that's some kind of contribution That we would like to see actually MK docs gl-deploy Would be cool if there are some specifics About GitLab Actually the code of MK docs Should be able to easily support it So if you are up for the task Please come with it But the facto no It doesn't support it yet But it absolutely can Okay Question the short one Is it possible to localize the title of a website? Yes, everything is You have all those options On the MK docs YAML configuration file So everything can be Can be Localized Sorry This is done through the MK docs Internalization plugin Which if you go on the readme You have a specific section explaining How to add translations For all the elements and all the titles Including the Including all the navigation titles So that includes the site name Okay, so that's the question now The chat is just filled with applause That you have really Given the audience something that they wanted Thank you very much for doing the presentation And I hope you're going to enjoy the rest of the week Thank you