How To Create STUNNING Code Documentation With MkDocs Material Theme

[@james-willett]

🧐 Making your documentation look stunning is a breeze with MkDocs and the Material theme! By following this video, you can have your documentation portal published online in minutes. Let me know if you want to see more content like this, and I'll make a more in-depth tutorial!

[@ahafeezs]

I'm the 667th subs. Cheers!

[@james-willett]

@@ahafeezs thanks for subscribing!

[@ahafeezs]

@@james-willett ​ I utilize it in one my my project documentation and it works like a charm. I wonder how can we do three things: 1. Set auto update date for the copyright. 2. Enforce/make the dark theme as default and light mode via turn off the toggle. 3. Change the favicon. I tried the same way I put a favicon in html in the indexDOTmd, none of them worked. Cheers!

[@james-willett]

@@ahafeezs sorry missed this comment before! I'll look to cover these topics in future video

[@mayanksindhvad]

You are definitely going to go big, happy to be one of the initial subscribers ! Love the way you zoom in and zoom out with that little whoosh sound effect. The content is on point, stepwise explanation, just amazing. Two requests: 1. Can you please share your VSCode theme settings? 2. How to integrate Azure Static WebApp with this?

[@james-willett]

Thanks Mayank for your feedback! I’m not sure on Azure WebApp to be honest, but for the VSCode settings I think I got these from a Colt Steele video , so maybe look on his channel 👍

[@kpicsoffice4246]

Really loved your editing style over the screen recording. Do you mind sharing your recording set up, editing workflow (fcpx?) and your tips/tricks to make such high quality videos? Would love a tutorial/series around this!!

[@james-willett]

Thank you! I'll add something to my pipeline around this, as a few people have asked now!

[@SapitoSucio]

Thank you for sharing the project, king! 🐸

[@TapeMonki]

Excellent video; I'm a novice with every tool you're using but you make an overwhelming topic seem more accessible.

[@rajaduraim1159]

Thank you so much for your step-by-step instructions video❤ Subscribed & Liked

[@james-willett]

Thanks for subbing!

[@jccorman5848]

Great intro. MkDocs can also be used to build a blog, which is what'll do. I have the same Washington Nationals hat in blue, but It hasn't given me any of your coding superpowers ;-)

[@james-willett]

Thanks JC - yes I’ve also used MkDoc Material with the Blog Plugin - will make a video on that at some point ! I bought the hat as I love the W on it , rather than being much of a Nationals fan 😂 - would love a blue one though !

[@wenyang5916]

Thank you so much! Brilliant video

[@waynesworldfishing]

errr NO WILL! This looks really good. With loads of options for a multitude of potential outcomes. Loving the videos fella keep up the good work 👍

[@james-willett]

Thank you mate!!

[@bambo5243]

wow great video, got a task to make a code documentation from work in mkdcos and this really helps. thanks

[@james-willett]

Glad to hear that! Got more content planned soon 👍

[@bambo5243]

@@james-willett awesome! i have a Question i hope you could help me with; i want to make a docu with mkdocs for our github at work. Is there a way to do it without git pages or other hosting sites. Just with a repository. We have one setup with a README and that works, but i cant figure it out with mkdocs. I hope you understand me. Thanks

[@james-willett]

@@bambo5243 To be honest I'm not sure how to do it without hosting the content at least on some platform, theres a few guides for platforms other than Git here - squidfunk.github.io/mkdocs-material/publishing-your-site/#other You might want to try posting on the discussion forum, to see if there is a way - github.com/squidfunk/mkdocs-material/discussions

[@bambo5243]

@@james-willett Allright i will check that out , thank you.

[@ArtiomK]

just awesome. Thank you

[@Cleverjimmade]

Very good tutorial, thank you

[@pranjal86able]

ya, this channel is going to blow up. Cool graphics; impressed by the fact that you created that whole thing in ~25 minutes (looking at your commit history).

[@james-willett]

Thank you, I appreciate that! - lots more content planned :)

[@Clickalgo]

Excellent presentation, thank you.

[@systemslave510]

Id like to see a deep dive tutorial. That's an awesome library

[@james-willett]

Thanks Tyler for letting me know , agree it is awesome ! We are just starting to use it heavily to document a new Platform Engineering project at work. Will add a deep dive video to my pipeline 👍

[@kevinc.7730]

@@james-willett I'll second that. From someone who instructs technical concepts for a living, you are a natural. Can't wait to see more

[@james-willett]

@@kevinc.7730 thanks - I really appreciate you saying that. More content on the way !

[@eugeniogonzato]

Very hight quoality tutorial !! thanks

[@james-willett]

Thanks Eugenio! Currently working on a new MkDocs Material video - out in a few days!

[@buildfromzero]

Thanks for sharing

[@keilmillerjr9701]

Excellent video. Thank you!

[@sagartamang0000]

Wow, this is so awesome!

[@holgerflick]

Would you mind telling me what plugin you use for your terminal? It looks absolutely beautiful and very organized!

[@james-willett]

I get asked that a lot Holger, maybe I should make a video 😂 It's using a ZSH skin called Powerlevel 10k - github.com/romkatv/powerlevel10k

[@hjwiko]

@@james-willett Also interested to know what auto-complete you're using on your terminal. Thanks

[@deepthitheresa1]

nice video! Your command prompt looks so cool! How does it look like that?

[@james-willett]

Check this tutorial www.freecodecamp.org/news/jazz-up-your-bash-terminal-a-step-by-step-guide-with-pictures-80267554cb22/

[@charlesuneze4920]

Nice tutorial, James. What terminal theme do you use?

[@LeslieMorgan-o3k]

Hermiston Spring

[@neurochannels]

Thanks for this really helpful video! I'd love an example where you use mkdocstrings to make (numpy) docstrings render in a nice way. I really like mkdocs, except in this one area: the function/class reference docs just aren't impressive (compared to sphinx), at least in my hands.

[@ghostza1209]

Thanks this help me a lot

[@james-willett]

Glad to hear it! Thanks for commenting :)

[@navdeepsharma-g9i]

Hi James Can you make video on plugins? multi-repo plugin in window or others It would be very helpful for that guys which using one project with multiple repos.

[@योगीगुरु]

very good work

[@monkyout]

Thank you.

[@james-willett]

You're welcome!

[@dt1926]

`source venv/bin/activate` didn't work for me on win 10, needed just `venv\Scripts\activate` dropping the source

[@dev_neptune]

thanks man

[@garyjo3229]

This .yml not working in the windows?

[@testautomate6307]

Hi, thanks for a cool guide :-). I have followed all yours stepes, but I don´t see "gh-pages" in select branch list (14:10). What do I do wrong ?

[@astraloby]

same! did you figure it out?

[@xManster123]

@@astraloby Installing GitHub CLI fixed the error while typing "mkdocs gh-deploy" in the VS Code Terminal. Now it's working for me.

[@chikosan99]

such a beautiful idea!

[@james-willett]

Thank you! 😊

[@NassiSchijf]

Is it possible to add some more info to Prerequisites? I followed everything, but I cannot run the command git clone from my Windows CMD. I guess I need to install something? But nowhere is it explained what is needed to run the command.

[@james-willett]

I should have made it clearer this tutorial is recorded on Mac, not Windows. It is mostly the same, but there are some small differences with the commands and running Python

[@MrMal0w]

Hi, very nice video ! Maybe a stupid question : when publishing to GitHub, is there a possibility to manage read permission ? Public ?

[@james-willett]

Hi Line - thanks for your comment. As we are publishing to GitHub pages, you can check here regarding visibility settings: docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site

[@charlie3502]

Excellent tutorial, James. I am unable to see the dark mode toggle button on my mkdocs site. What might be the reason?

[@james-willett]

Thanks Charlie - glad it was helpful. Honestly I'm not sure without seeing your code. However, I am currently working on a brand new getting started video for MkDocs Material where I cover this, so following that might help. It should be out in a week or so.

[@bryceshirley9285]

Thanks for your video! It was super helpful :) I've had issues rendering html... Do any of these features and plugins in the yml file cause issues when rendering images using html in your markdown files? I can't seem to get the above to render (the images are in the docs directly with the markdown file)

[@james-willett]

Thanks for the kind words! I'm not aware of any issues with regards to rendering and plugin to be honest... I'm actually working on an updated version of this tutorial that should be out in a next next or two - so I'll keep an eye out for any issues around this in the latest version of the plugins

[@danielaalarcao4391]

Thanks!! ✨

[@pranjal86able]

I like streamlit more; diff use cases though

[@NassiSchijf]

I managed to set it up, but how do I make and publish changes?

[@james-willett]

i cover this in the video towards the end, how to publish to GitHub pages

[@cricketstories7531]

In the terminal, you are getting suggestions for git commands. Could you please guide me, how to enable them in VS code? Thanks

[@owlprotravels]

Muito bom. Nossa fica maravilhado com markdown, trás esse tipo de tecnologia. Algo simples. Mas que ganha muito potencial. Gostei de mais do vídeo. Bem claro, também documentação ser bem explicita. Acho muito bom também não ter ci apenas o GitHub, mas para outras plataformas também. Muito bom

[@james-willett]

thank you! 🔥

[@davidtevzadze4832]

A quick question. Is MkDocs only for python or can it be used for JS?

[@jatlineur]

can i use itu for blogging?

[@ccbode]

how does this change if you aren't on a mac?

[@kannansingaravelu]

how do I link a '.py' file to list the docstring using mkdocs. Also, how to rearrange the order of nav menus?

[@james-willett]

I'm not sure I understand the docstring question, could you elaborate? For reordering see if github.com/squidfunk/mkdocs-material/discussions/3482 is helpful

[@stijn_gamet]

If u pushed to github etc.., the material theme isn't there there weren't any failes

[@docpatel7399]

Is there a way to have a drop down in the top navigation for multiple pages, like having a languages that leads to a drop down with different types of languages?

[@james-willett]

I’ll check when im next at a computer , but I think that would require custom css or a specific plugin to achieve. You might want to check on the Material site if the feature is available- squidfunk.github.io/mkdocs-material/contributing/#creating-an-issue

[@risehighgames4341]

Hi, So is it free to use for commercial purposes ?

[@王子涵-c5f]

How can I configue my .yml document by my self? In your vedio, you just paste some code in the mkdocs.yml, but I do not know how to find these codes, can you help me? Very thanks!

[@vasilytyrnovsky9516]

Thank you. Very interesting. However, the config part (pymdownx) didn't work for me. Please tell me how to make this plugin friends with mcdocs. Can mcdocs be used as an alternative to evernote? Is it enough search engine power to make search in 1000 or more documents?

[@james-willett]

I would say Evernote and MkDocs are quite significantly different solutions. MkDocs is good for documenting a coding project, while Evernote is better at holding personal notes and offers many other features related to organisation and productivity.

[@anuragnair5]

Hi James, can you please help me resume working on the project, I closed the cmd and Vsc. now when I hit mkdocs serve, it gives me an error saying it's not recognized as the name of a cmdlet, function, script file/operable program.

[@james-willett]

I think you need to restart the Python virtual environment `source venv/bin/activate`

[@hajares2350]

PS C:\Users\dell\Desktop\doc> git push origin main ERROR: Permission to HajarEssaoudi/doc.git denied to deploy key fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.

[@ThomasVanhelden]

Could you create a tutorial (or direct me somewhere) on your iTerm2 configuration?

[@Naituf]

He probably uses powerlevel10k theme for zsh.

[@ThomasVanhelden]

@@NaitufIndeed! I was curious about his fonts and the specific configuration of powerlevel10k. Anyway, I have my own configuration now, and I use Warp.

[@qianyuewei1268]

Hi James, I tried to follow your tutorial and I encountered a problem, could you tell me your python version and pip version you used in this tutorial? Thanks first~

[@james-willett]

I forget the exactly version of python - whats the problem you are having? See if the steps on squidfunk.github.io/mkdocs-material/getting-started/ help

[@qianyuewei1268]

@@james-willett ​ get it work now thanks for replying :)

[@AbhishekSreesaila1232]

What terminal app are you using on the mac?

[@james-willett]

github.com/romkatv/powerlevel10k

[@KarlMiller]

Why are you putting a copyright notice on youtube tutorial page that is intended to be copied and freely used?

[@james-willett]

Hi Karl - fair point! I'm actually just trying to demonstrate how you can add a copyright to your own page... but you're right I could remove this :)

[@KarlMiller]

@@james-willett I didn't comment before, but the video was quite informative. I was looking for a quick way to share and document a github project and I haven't bothered to learn this part. It would also be interesting to see how to add notes about the github repo's "Project" issues, backlog list, versions and todo lists.

[@theVAULT909]

Since both Python and Python3 exist: what are you referring to, when you say 'Python'? Being explicit would help the less code-savvy folks.

[@james-willett]

Thanks Ronny - I was referring to Python 3

[@youtube-username-placeholder]

Sorry this comment confuses me. I always thought Python3 is Python… Are you talking about Python2 vs 3? 😅

[@anthonyhiscox]

​@@youtube-username-placeholder unless explicitly stated most references to Python will be 3, however older code bases are often Python 2. To make matters more confusing, I recently ran into a bug with PrivateGPT that was resolved by installing Python 3.10 rather than the 3.11 installed on my machine.

[@ArpenteurDeToile]

since january 2020, python2 is deprecated. what remains is just maintenance, so for the less tech savy python is python3. only dev doing old software maintenance might still use py2 ^^

[@dinoscheidt]

@OP If you assume Python2 in 2023, you have other issues.

[@Apeiron242]

Schtudio

[@creeksjtohchannel]

code . doesnt work

[@james-willett]

Need to have Visual Studio code installed

[@polasanivamshideshai2115]

C:\Users\91738\mkdocs-material-youtube-crashcourse>python -m venv venv Error: Command '['C:\\Users\\91738\\mkdocs-material-youtube-crashcourse\\venv\\Scripts\\python.exe', '-m', 'ensurepip', '--upgrade', '--default-pip']' returned non-zero exit status 1. I am getting this problem can pls slove it i already installed python 3.11 and vs code also

[@hajares2350]

me too if got an answer pls share i with me

[@polasanivamshideshai2115]

@@hajares2350 yes i got the solution for it

[@james-willett]

Looks like you are on windows, can you try these 3 commands: py -m venv env cd env Scripts\activate See this article: ordinarycoders.com/blog/article/python-virtual-environment

[@navdeepsharma-g9i]

Hi James Can you make video on plugins? multi-repo plugin in window or others It would be very helpful for that guys which using one project with multiple repos.

[@james-willett]

Thanks for the feedback! I'll look to add some new videos soon. I'm thinking to add one around the new Blog plugin that was recently released to open source :)