How To Create STUNNING Code Documentation With MkDocs Material Theme

Подписаться 1,9 тыс.

Просмотров 54 тыс.

50% 1

Learn how to create and host a stunning documentation portal on GitHub Pages using MkDocs and the Material theme
#MkDocs #GithubPages
Consider joining the channel: / @james-willett
▬▬▬▬▬▬ 🔗 Additional Info 🔗 ▬▬▬▬▬▬
🔗 GitHub Repo for this Video: github.com/james-willett/mkdo...
🔗 MkDocs Material Theme: squidfunk.github.io/mkdocs-ma...
🔗 MkDocs Material Documentation: squidfunk.github.io/mkdocs-ma...
▬▬▬▬▬▬ 💰 Sponsorships 💰 ▬▬▬▬▬▬
If you are interested in sponsoring this channel, please contact me on one of the channels below 👇
▬▬▬▬▬▬ 👋 Contact me 👋 ▬▬▬▬▬▬
➡ Twitter: / thejameswillett
➡ LinkedIn: / willettjames
▬▬▬▬▬▬ ⏱ Timecodes ⏱ ▬▬▬▬▬▬
(00:00:00) Intro
(00:01:10) Prerequisites to follow this video
(00:01:50) Create GitHub repository
(00:02:45) Create Virtual Environment
(00:03:25) Create MkDocs site
(00:03:55) Run MkDocs Locally
(00:04:18) Install Material Plugin
(00:05:33) Add New Features
(00:06:34) Add Additional Page
(00:07:05) Add Social Icons
(00:07:35) Add Copyright message
(00:07:55) Markdown Extensions for Code Highlights
(00:11:35) Add Emojis and Icons
(00:12:20) Publish Documentation on GitHub Pages
(00:15:00) Outro

Наука

Опубликовано:

27 июн 2024

Ссылка:

Скачать:

Готовим ссылку...

Добавить в:

Мой плейлист

Посмотреть позже

Комментарии : 108

@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

@wenyang5916 11 месяцев назад

Thank you so much! Brilliant video

@SapitoSucio Год назад

Thank you for sharing the project, king! 🐸

@ArtiomK Год назад

just awesome. Thank you

@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 👍

@TapeMonki 6 месяцев назад

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

@keilmillerjr9701 8 месяцев назад

Excellent video. Thank you!

@Clickalgo 8 месяцев назад

Excellent presentation, thank you.

@sagartamang0000 2 месяца назад

Wow, this is so awesome!

@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 :)

@buildfromzero Год назад

Thanks for sharing

@rajaduraim1159 10 месяцев назад

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

@james-willett 9 месяцев назад

Thanks for subbing!

@chikosan99 Год назад

such a beautiful idea!

@james-willett Год назад

Thank you! 😊

@danielaalarcao4391 4 месяца назад

Thanks!! ✨

@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!!

@temples-of-india 2 месяца назад

very good work

@ghostza1209 10 месяцев назад

Thanks this help me a lot

@james-willett 10 месяцев назад

Glad to hear it! Thanks for commenting :)

@eugeniogonzato Год назад

Very hight quoality tutorial !! thanks

@james-willett Год назад

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

@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!

@monkyout Год назад

Thank you.

@james-willett 10 месяцев назад

You're welcome!

@charlesuneze4920 5 месяцев назад

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

@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.

@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 !

@neurochannels 5 месяцев назад

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.

@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 !

@user-pv8oi5ol1i 10 месяцев назад

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.

@deepthitheresa1 9 дней назад

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

@james-willett 5 дней назад

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

@pranjal86able Год назад

I like streamlit more; diff use cases though

@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 5 месяцев назад

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

@cricketstories7531 2 месяца назад

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

@risehighgames4341 6 месяцев назад

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

@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

@testautomate6307 8 месяцев назад

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 3 месяца назад

same! did you figure it out?

@garyjo3229 4 месяца назад

This .yml not working in the windows?

@user-ll3pf2de9m 4 месяца назад

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!

@davidtevzadze4832 2 месяца назад

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

@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

@AbhishekSreesaila1232 Год назад

What terminal app are you using on the mac?

@james-willett Год назад

github.com/romkatv/powerlevel10k

@ccbode 7 месяцев назад

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

@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 10 месяцев назад

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 9 месяцев назад

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

@user-om8fi5ow4g 10 месяцев назад

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 9 месяцев назад

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

@user-om8fi5ow4g 10 месяцев назад

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

@james-willett 9 месяцев назад

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

@stijn_gamet 8 месяцев назад

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

@hajares2350 9 месяцев назад

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.

@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 :)

@ThomasVanhelden 7 месяцев назад

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

@Naituf 4 месяца назад

He probably uses powerlevel10k theme for zsh.

@ThomasVanhelden 4 месяца назад

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

@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 11 месяцев назад

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

@anthonyhiscox 11 месяцев назад

@@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 9 месяцев назад

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 9 месяцев назад

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

@edd198.92. Год назад

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! 🔥

@Apeiron242 10 месяцев назад

Schtudio

@dt1926 10 месяцев назад

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

@dev_neptune Месяц назад

thanks man

@creeksjtohchannel Месяц назад

code . doesnt work

@james-willett 5 дней назад

Need to have Visual Studio code installed

@polasanivamshideshai2115 11 месяцев назад

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 10 месяцев назад

me too if got an answer pls share i with me

@polasanivamshideshai2115 10 месяцев назад

@@hajares2350 yes i got the solution for it

@james-willett 10 месяцев назад

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

@user-pv8oi5ol1i 10 месяцев назад

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 10 месяцев назад

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 :)