How To Create STUNNING Code Documentation With MkDocs Material Theme

Поділитися
Вставка
  • Опубліковано 12 гру 2024

КОМЕНТАРІ • 120

  • @james-willett
    @james-willett  Рік тому +14

    🧐 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
      @ahafeezs Рік тому +1

      I'm the 667th subs. Cheers!

    • @james-willett
      @james-willett  Рік тому +1

      @@ahafeezs thanks for subscribing!

    • @ahafeezs
      @ahafeezs Рік тому +1

      @@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
      @james-willett  Рік тому +2

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

  • @mayanksindhvad
    @mayanksindhvad Рік тому +5

    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
      @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
    @TapeMonki 11 місяців тому

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

  • @SapitoSucio
    @SapitoSucio Рік тому +2

    Thank you for sharing the project, king! 🐸

  • @wenyang5916
    @wenyang5916 Рік тому +2

    Thank you so much! Brilliant video

  • @kpicsoffice4246
    @kpicsoffice4246 Рік тому +3

    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
      @james-willett  Рік тому +1

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

  • @rajaduraim1159
    @rajaduraim1159 Рік тому +2

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

  • @bambo5243
    @bambo5243 Рік тому +1

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

    • @james-willett
      @james-willett  Рік тому +1

      Glad to hear that! Got more content planned soon 👍

    • @bambo5243
      @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
      @james-willett  Рік тому +1

      @@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
      @bambo5243 Рік тому

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

  • @waynesworldfishing
    @waynesworldfishing Рік тому +1

    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 👍

  • @ArtiomK
    @ArtiomK Рік тому +1

    just awesome. Thank you

  • @Cleverjimmade
    @Cleverjimmade Рік тому +1

    Very good tutorial, thank you

  • @keilmillerjr9701
    @keilmillerjr9701 Рік тому

    Excellent video. Thank you!

  • @systemslave510
    @systemslave510 Рік тому +2

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

    • @james-willett
      @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
      @kevinc.7730 Рік тому +1

      @@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
      @james-willett  Рік тому

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

  • @eugeniogonzato
    @eugeniogonzato Рік тому +1

    Very hight quoality tutorial !! thanks

    • @james-willett
      @james-willett  Рік тому

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

  • @pranjal86able
    @pranjal86able Рік тому +1

    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
      @james-willett  Рік тому

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

  • @sagartamang0000
    @sagartamang0000 7 місяців тому

    Wow, this is so awesome!

  • @holgerflick
    @holgerflick Рік тому +1

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

    • @james-willett
      @james-willett  Рік тому +1

      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
      @hjwiko 11 місяців тому

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

  • @testautomate6307
    @testautomate6307 Рік тому +2

    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
      @astraloby 9 місяців тому

      same! did you figure it out?

    • @xManster123
      @xManster123 4 місяці тому

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

  • @jccorman5848
    @jccorman5848 Рік тому +1

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

  • @charlesuneze
    @charlesuneze 11 місяців тому

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

  • @neurochannels
    @neurochannels 11 місяців тому

    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.

  • @chikosan99
    @chikosan99 Рік тому

    such a beautiful idea!

  • @buildfromzero
    @buildfromzero Рік тому +1

    Thanks for sharing

  • @ghostza1209
    @ghostza1209 Рік тому +1

    Thanks this help me a lot

  • @navdeepsharma-g9i
    @navdeepsharma-g9i Рік тому +1

    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.

  • @cricketstories7531
    @cricketstories7531 8 місяців тому

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

  • @ccbode
    @ccbode Рік тому +1

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

  • @deepthitheresa1
    @deepthitheresa1 5 місяців тому

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

    • @james-willett
      @james-willett  5 місяців тому

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

  • @garyjo3229
    @garyjo3229 10 місяців тому +1

    This .yml not working in the windows?

  • @charlie3502
    @charlie3502 3 місяці тому

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

    • @james-willett
      @james-willett  3 місяці тому +1

      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.

  • @MrMal0w
    @MrMal0w Рік тому +1

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

    • @james-willett
      @james-willett  Рік тому +1

      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

  • @NassiSchijf
    @NassiSchijf Рік тому +1

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

  • @monkyout
    @monkyout Рік тому +1

    Thank you.

  • @योगीगुरु
    @योगीगुरु 7 місяців тому

    very good work

  • @NassiSchijf
    @NassiSchijf Рік тому +1

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

    • @james-willett
      @james-willett  Рік тому

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

  • @danielaalarcao4391
    @danielaalarcao4391 9 місяців тому

    Thanks!! ✨

  • @bryceshirley9285
    @bryceshirley9285 3 місяці тому

    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
      @james-willett  3 місяці тому

      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

  • @jatlineur
    @jatlineur 2 місяці тому +1

    can i use itu for blogging?

    • @james-willett
      @james-willett  2 місяці тому

      Yes its amazing for a blog. Hoping to create a video for this soon.

  • @stijn_gamet
    @stijn_gamet Рік тому

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

  • @Clickalgo
    @Clickalgo Рік тому

    Excellent presentation, thank you.

  • @risehighgames4341
    @risehighgames4341 11 місяців тому

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

  • @docpatel7399
    @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
      @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

  • @王子涵-c5f
    @王子涵-c5f 9 місяців тому

    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!

  • @pranjal86able
    @pranjal86able Рік тому +1

    I like streamlit more; diff use cases though

  • @kannansingaravelu
    @kannansingaravelu 3 місяці тому

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

    • @james-willett
      @james-willett  3 місяці тому

      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

  • @davidtevzadze4832
    @davidtevzadze4832 8 місяців тому

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

  • @eazygfx4815
    @eazygfx4815 12 днів тому

    It published but it doesnt look anywhere like material, the sidebar etc is missing xD

    • @james-willett
      @james-willett  11 днів тому

      Hmm not sure why that is, can you try following my other tutorial? ua-cam.com/video/xlABhbnNrfI/v-deo.htmlsi=HwXVyNJ-QstEeNwp

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

  • @anuragnair5
    @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
      @james-willett  Рік тому

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

  • @dt1926
    @dt1926 Рік тому +3

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

  • @AbhishekSreesaila1232
    @AbhishekSreesaila1232 Рік тому

    What terminal app are you using on the mac?

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

  • @ThomasVanhelden
    @ThomasVanhelden Рік тому

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

    • @Naituf
      @Naituf 10 місяців тому +1

      He probably uses powerlevel10k theme for zsh.

    • @ThomasVanhelden
      @ThomasVanhelden 10 місяців тому

      @@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
    @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
      @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
      @qianyuewei1268 Рік тому

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

  • @KarlMiller
    @KarlMiller Рік тому

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

    • @james-willett
      @james-willett  Рік тому +1

      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
      @KarlMiller Рік тому +1

      @@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
    @theVAULT909 Рік тому +3

    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
      @james-willett  Рік тому +2

      Thanks Ronny - I was referring to Python 3

    • @youtube-username-placeholder
      @youtube-username-placeholder Рік тому +1

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

    • @anthonyhiscox
      @anthonyhiscox Рік тому +1

      ​@@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
      @ArpenteurDeToile Рік тому +2

      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
      @dinoscheidt Рік тому +2

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

  • @Apeiron242
    @Apeiron242 Рік тому

    Schtudio

  • @owlprotravels
    @owlprotravels Рік тому +1

    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

  • @creeksjtohchannel
    @creeksjtohchannel 6 місяців тому

    code . doesnt work

    • @james-willett
      @james-willett  5 місяців тому

      Need to have Visual Studio code installed

  • @polasanivamshideshai2115
    @polasanivamshideshai2115 Рік тому +1

    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
      @hajares2350 Рік тому +1

      me too
      if got an answer pls share i with me

    • @polasanivamshideshai2115
      @polasanivamshideshai2115 Рік тому

      @@hajares2350 yes i got the solution for it

    • @james-willett
      @james-willett  Рік тому +2

      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
    @navdeepsharma-g9i Рік тому +1

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