How To Create STUNNING Code Documentation With MkDocs Material Theme
ฝัง
- เผยแพร่เมื่อ 14 ก.ค. 2024
- 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 - วิทยาศาสตร์และเทคโนโลยี
![ชวนน้องลงทุ่ง - เงาะน้อยเพชรบ้านแพง X น้องมายด์ [ Music Video ] Official Saman Music](http://i.ytimg.com/vi/Bq7Hw9culjE/mqdefault.jpg)
🧐 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!
I'm the 667th subs. Cheers!
@@ahafeezs thanks for subscribing!
@@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!
@@ahafeezs sorry missed this comment before! I'll look to cover these topics in future video
Thank you for sharing the project, king! 🐸
Thank you so much! Brilliant video
Excellent video; I'm a novice with every tool you're using but you make an overwhelming topic seem more accessible.
just awesome. Thank you
Wow, this is so awesome!
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?
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 👍
Excellent presentation, thank you.
Excellent video. Thank you!
Very good tutorial, thank you
Thank you so much for your step-by-step instructions video❤
Subscribed & Liked
Thanks for subbing!
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).
Thank you, I appreciate that! - lots more content planned :)
Thanks for sharing
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 👍
Thank you mate!!
Thanks!! ✨
very good work
such a beautiful idea!
Thank you! 😊
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!!
Thank you! I'll add something to my pipeline around this, as a few people have asked now!
Thanks this help me a lot
Glad to hear it! Thanks for commenting :)
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 ;-)
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 !
Thank you.
You're welcome!
Very hight quoality tutorial !! thanks
Thanks Eugenio! Currently working on a new MkDocs Material video - out in a few days!
wow great video, got a task to make a code documentation from work in mkdcos and this really helps. thanks
Glad to hear that! Got more content planned soon 👍
@@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
@@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
@@james-willett Allright i will check that out , thank you.
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.
Id like to see a deep dive tutorial. That's an awesome library
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 👍
@@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
@@kevinc.7730 thanks - I really appreciate you saying that. More content on the way !
Nice tutorial, James. What terminal theme do you use?
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.
I like streamlit more; diff use cases though
nice video! Your command prompt looks so cool! How does it look like that?
Check this tutorial www.freecodecamp.org/news/jazz-up-your-bash-terminal-a-step-by-step-guide-with-pictures-80267554cb22/
This .yml not working in the windows?
In the terminal, you are getting suggestions for git commands.
Could you please guide me, how to enable them in VS code?
Thanks
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 ?
same! did you figure it out?
Hi, So is it free to use for commercial purposes ?
Would you mind telling me what plugin you use for your terminal? It looks absolutely beautiful and very organized!
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
@@james-willett Also interested to know what auto-complete you're using on your terminal. Thanks
Hi, very nice video ! Maybe a stupid question : when publishing to GitHub, is there a possibility to manage read permission ? Public ?
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
how does this change if you aren't on a mac?
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?
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
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!
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?
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.
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.
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
A quick question. Is MkDocs only for python or can it be used for JS?
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.
I think you need to restart the Python virtual environment `source venv/bin/activate`
What terminal app are you using on the mac?
github.com/romkatv/powerlevel10k
I managed to set it up, but how do I make and publish changes?
i cover this in the video towards the end, how to publish to GitHub pages
If u pushed to github etc.., the material theme isn't there
there weren't any failes
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.
Could you create a tutorial (or direct me somewhere) on your iTerm2 configuration?
He probably uses powerlevel10k theme for zsh.
@@NaitufIndeed! I was curious about his fonts and the specific configuration of powerlevel10k.
Anyway, I have my own configuration now, and I use Warp.
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
thank you! 🔥
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~
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
@@james-willett get it work now thanks for replying :)
Why are you putting a copyright notice on youtube tutorial page that is intended to be copied and freely used?
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 :)
@@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.
Since both Python and Python3 exist: what are you referring to, when you say 'Python'? Being explicit would help the less code-savvy folks.
Thanks Ronny - I was referring to Python 3
Sorry this comment confuses me. I always thought Python3 is Python… Are you talking about Python2 vs 3? 😅
@@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.
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 ^^
@OP If you assume Python2 in 2023, you have other issues.
Schtudio
`source venv/bin/activate` didn't work for me on win 10, needed just `venv\Scripts\activate` dropping the source
thanks man
code . doesnt work
Need to have Visual Studio code installed
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
me too
if got an answer pls share i with me
@@hajares2350 yes i got the solution for it
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
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.
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 :)