Material for MkDocs: Full Tutorial To Build And Deploy Your Docs Portal

[@james-willett]

🧐 Transform your documentation with MkDocs and the Material theme! Follow this guide to publish your portal online in no time. Want more content like this? Let me know, and I'll dive deeper in future tutorials!

[@gabrielpimentelgomes3195]

Great tutorial! Thank you for sharing your nice work

[@VrejGaming]

One of the best MkDocs tutorials I have watched! Incredibly helpful, thank you!

[@james-willett]

Appreciate that - thank you ! 🙏

[@rijutsu]

A quick note to say that I've spent the better part of the past three days using this video to build my own set of pages and I can't thank you enough. The presentation, the links, the code examples, the chapters/timestamps in the video, and just so much of this was wildly helpful. Thank you so much for your effort! :D

[@james-willett]

Thanks for taking the time to write this comment. Lots more content planned ☺️

[@lockdown50559]

Man, you made this video just in time for me! I think that you are an amazing presenter.

[@james-willett]

Thanks - appreciate your feedback ☺️

[@CrafterXD2000]

Really nice stunning video! Thanks a lot! 🔥🔥

[@james-willett]

Thanks so much - appreciate it.

[@mdlsvensson]

Incredibly concise and well put together video. Thank a lot!

[@james-willett]

Glad it was helpful!

[@Daniel-ops]

Thanks for the video James! just started with mkdocs to host my personal blog and loving it so far.

[@james-willett]

Great to hear! Please share a link , would love to take a look

[@tillcarlos664]

Wow, I love this video style. It's well edited and well spoken!

[@james-willett]

Thanks so much for this feedback - highly appreciated.

[@JohnnieWalkerGreen]

Thank You!

[@shadow_1363]

Great video, very helpful!

[@james-willett]

Glad to hear that! Thanks for letting me know :)

[@gabrielbronzattimoro7953]

That is an incredible content 🎉 Thank you so much for sharing this with us!

[@james-willett]

Glad you enjoyed it!

[@mreduar]

Super video! Thanks for this!

[@james-willett]

Glad you liked it!

[@AndreiKatin]

Super

[@eazygfx4815]

what about customizing theme further than the basics (partial overrides, custom css which i've done) and then publishing it to gh pages

[@mikeball4959]

Superb video, thank you. When I get to the last step though I'm getting Page not found on the URL rather than the documentation. Any ideas?

[@james-willett]

Check the GitHub settings , maybe you missed setting to the new branch ?

[@RonenSigan]

How many levels can a ToC have (left pane navigation)? For example, can these amount of levels be supported: APIs -> Weather Forecast Requests-> Daily --> Centigrade Thanks

[@james-willett]

Good question - I’m pretty sure you can nest multiple times. Make sure you enable “navigation.sections” in your config . See squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-sections

[@kapanadze]

❤❤❤❤❤

[@hectormanuelsanchezgarcia9243]

These videos are great, thank you! this content is very good quality. Question: do you know how to implement authentication? like with Django maybe? this would be for a documentation site that's private to a company for example to have it private for team members only.

[@james-willett]

Thanks for the kind words. Maybe try staticrypt? github.com/robinmoisson/staticrypt

[@599mighty6]

I looked at your blog site and studied the source code of your site on your github for a while, and I didn't understand how you implemented the author info on the left and the back to index button in your post!

[@james-willett]

I'm actually working on a new video that'll showcase how to setup a blog just like mine (but with more features). To answer your question, I think the author info is part of the Insiders program currently - see squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#adding-author-profiles I'll be sure to cover this functionality in my next video

[@599mighty6]

@james-willett thanks

[@ApxuBbI]

Virtual environment for python is created, so if your loaded files will reside in project folder, and wont clutter APPDATA (Windows) ?

[@james-willett]

Yes, when you create a Python virtual environment inside your project folder, it will isolate all the installed packages and dependencies within that environment. This means that the files related to the virtual environment (e.g., Python executables, pip, and any installed packages) will reside in the project folder itself, and nott clutter global directories like APPDATA on Windows.

[@abepeterson]

What setting do we implement so every time I push to github it stops resetting my custom URL! I have been trying for weeks, I even added the CNAME.txt to the docs directory and still, when I do a push it drops the custom URL. The CNAME folder shows the URL, but no resolution unless I go to the repo github page settings and set it again.

[@james-willett]

Sorry to hear you are having this problem. It's hard for me to diagnose without seeing your repo, but theres a few things you might want to try: 1. Ensure the CNAME File is in the Correct Location The CNAME file should be in your source directory (e.g., docs/) so that it gets copied to the root of the built site during deployment. 2. Modify Your GitHub Actions or Deployment Script GitHub Actions might be overwriting or exclude the CNAME file during each deployment. You can modify your workflow to ensure that the CNAME file is always included in the deployment. You can add a step to ensure that the CNAME file is copied into the build output before deploying, e.g: jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: '3.x' - name: Install dependencies run: pip install mkdocs mkdocs-material - name: Build site run: mkdocs build - name: Add CNAME file run: echo "yourcustomdomain.com" > ./site/CNAME - name: Deploy to GitHub Pages run: mkdocs gh-deploy --force 3. Check GitHub Pages Settings Check your repository's GitHub Pages settings, Go to Settings > Pages. Make sure that under "Custom domain," your custom domain is listed and saved. Hope that helps...

[@yehorpererva9735]

Excellent tutorial. If there will be a next tutorial, could you please cover adding functionality to pdf export. Something like a plugin to add the "export to pdf" button for each page.

[@james-willett]

Thanks for the great suggestion. I've added it to my list and I'll look to cover it in a follow up video.

[@soymadip]

i wanna put the docs in a docs branch and wannna deploy from there. is this possible?

[@james-willett]

Yes its possible. By default, MkDocs uses the gh-pages branch for deployment. However, you can change this behavior by specifying the remote-branch option in the mkdocs.yml configuration file or by passing it as a command-line argument. For example, if you want to deploy from the docs branch, you can run: mkdocs gh-deploy --remote-branch docs Make sure to also update the branch in the GitHub settings when you are configuring GitHub Pages

[@eazygfx4815]

Not sure if it has changed but for windows the commands for python are: python --version python3 --version

[@Jopcopin]

10/10 😎

[@neo-mashiro]

Thanks for the great video, this is really helpful. For the Github Actions though, I don't think the caching step is set up correctly because the ".cache" folder just doesn't exist. If you jump into the action logs, you will see something like this: Warning: Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved.

[@james-willett]

Thanks for commenting. I think the ".cache" folder gets created earlier in the video when we did `pip install `or `mkdocs build`

[@ousseynoungom9937]

short video with all you need to know to start, congrate

[@james-willett]

Thanks!