Update 08/2024 - This video is still getting a regular amount of views and I have questions once in a while on how to do something particular with the platform. These questions are good because they help me know what areas I need to focus on for the part 2 video, because my intentions originally were to focus more on the SEO aspects. The site is working excellent and I plan to stay with the platform for the long haul. It looks great, loads fast, and works well for a lot of content. The initial setup is the hardest part of the process, and the maintenance and adding new content is straightforward. I've been working on a large update for the site as time allows for me to make the content. One thing I'll add to the main section is some more written instructions w/ photos for the trickier components of making your own site. In the replies to comments here, you can find answers for some of the issues you might be having in the process. If you'd like detailed help with troubleshooting, feel free to join my Discord server: discord.gg/AGJEe3xXC9 If I can see photos of your editor, it's much easier for me to know if there's formatting issues, which is something MkDocs is sensitive with. Original comment below: Here's the list of some of the commands followed by comments (noted with #, for those new to this, don't actually include # or anything after when trying to run commands) for those that want them. I will have a full write up on my new website sometime in the next few weeks to fill in any of the gaps from the documentation, with a more comprehensive list of code and commands. To start, go to the main website folder you have and right click and select the terminal. Use the commands in the following order: python -m venv venv # When using this command, you can change the second venv to create a folder name of your choice. I went with venv because it was easiest to use. You can use a different folder name by doing this: python -m venv foldername Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process # This is needed to let PowerShell run the script needed to launch the site. venv\Scripts\Activate.ps1 # This launches the PowerShell script needed to start working on the site. code . # If you're using VS Code as your editor, this will fire it up. mkdocs serve # Put this in either the terminal window or in the VS Code terminal to serve the local version of your site. You'll need to see your site as you start making changes to make sure everything looks good after each save, since some changes may cause things to break and will need to be fixed right away. :root { --md-admonition-icon--youtube: url('data:image/svg+xml;charset=utf-8,') } .md-typeset .admonition.youtube, .md-typeset details.youtube { border-color: rgb(255, 0, 0); } .md-typeset .youtube > .admonition-title, .md-typeset .youtube > summary { background-color: rgba(255, 0, 0, 0.1); } .md-typeset .youtube > .admonition-title::before, .md-typeset .youtube > summary::before { background-color: rgb(255, 0, 0); -webkit-mask-image: var(--md-admonition-icon--youtube); mask-image: var(--md-admonition-icon--youtube); } # The above is the YT admonition I made. You can change this to whatever you want to make custom admonitions. To change the icon used, go to the MkDocs repo here: github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons Find the icon you want and click on it to pull up the photo. Look to the upper left and you'll see a tab called "code." That will give you that long ass path for the icon that you need to paste in like I did for the above example. If you try to use a simple path, i.e. icons/fontawesome/someicon, then it won't work. The custom admonition code needs to go here: yoursitename/docs/stylesheets/extra.css You'll need to create the css file in whatever code editor you use. Then you can just paste and go. {% extends "base.html" %} {% block announce %} You can follow me on
{% include ".icons/fontawesome/brands/twitter.svg" %}
Twitter and
{% include ".icons/fontawesome/brands/youtube.svg" %}
TH-cam. To see what has been updated on the website, refer to the
{% include ".icons/octicons/log-24.svg" %}
changelog. Currently, the OPSEC section has been revamped for the release of the new site design. The rework of the other sections is in progress. {% endblock %} # The above code is what I used to for the banner on the site. This needs to go in yoursitename/overrides/main.html Once again, just use your code editor to make the file. Also, when you make changes and save to an HTML file, it won't show right away, at least when using VS Code. You'll need to click somewhere else in VS, like into a page that you're working on and save there (even if you haven't made any changes, this is just a weird glitch), then the HTML file changes will get saved so you can see the changes made in the browser window. I'll add more detail to this when I make the site page tutorial. If you have any questions on this or anything else when making the site, please let me know. I'll be making a part 2 video in about a month.
Something I forgot to add to the video - if you want to make a home landing page like how MkDocs Material has, you'll have to make one using HTML. This can get quite a lot more complicated than just using the docs part of the site. It wasn't the only reason I kept my main site separate from MkDocs, but it did have some factor. If you wanted to have more content that would be better served by using a different format than MkDocs, you could set it up where your other content is designed on a separate platform (i.e. Squarespace) and have direct links to the MkDocs section and use a subdomain.
Your tutorial is invaluable, thank you! I'd love to see a video exploring the built-in Tags plugin, focusing on its non-sponsored features. Keep up the great work!
Thanks for supporting! I'll add that to the list for the follow up video. I'll also be adding some supplemental docs as well to help clarify setting some of this stuff up.
Thanks! The icon there was actually not something I had intended to do - it just got placed there with how I set the site up. I've got the main index.md file in the docs folder as the homepage. At the top of the page, I put icon:octicons/book-16. Then in mkdocs.yml, I have my homepage nav set like this: nav: - Home: kenharris.io - Knowledge Base: - 'Start Here': - 'Start Here': index.md
Sounds good, I'll swing back around a bit later and paste the code in. Is there anything in particular you were looking for or would you like all the custom sections that I made? Also, if there's anything else you'd like clarification on, please let me know. I'm going to start working on a part 2 for this soon to fill in the gaps that this video had.
Alright my man, I got that code pasted up in the pinned comment! If you have any questions, feel free to ask. I'm going to start working on the full write up sometime in the next few weeks.
@@KenHarrisio Like for example, pipenv install mkdocs, then it will automatically create a virtual env for you, while installing the packages only on the virtual env. Then after installation, you can just exec the command “pipenv run mkdocs serve” I’ll also look forward seeing these in your future videos 😃
@@skyzane2735Damn, that's awesome! I'll give that a spin. Part 2 is probably a month or two away. Right now, I'm doing some SEO testing for the platform.
@@skyzane2735 I'll actually be doing a couple SEO videos (none are on the channel yet). The first will be for MkDocs and the specific things that need to be done for it. I'm experimenting with a few different things on the platform to see what kind of differences it makes. I'll also be making a general SEO video, which probably won't be until late May or sometime in June. Google is rolling out an update on May 5 to cut down on the amount of low quality content. They didn't specifically say this, but it reads like anyone who has copy pasted anything from GPT is going to get their site deranked. Google is giving site owners a couple months to get this fixed. They also want to fix other quality issues. I.e. someone Googles a question and the answer needs to be 10 paragraphs to give a proper answer. Some sites will try to give a generic answer with one or two paragraphs but it didn't help the person at all. They are also penalizing content like that. I want to see what happens to search after these changes roll out. I think it'll have a pretty sizeable impact on how people need to approach the content aspect of SEO. I read the info they released, and it sounds like the focus is going to be helpful (so generally in-depth) human made content. It's looking like everything else should stay the same though, such as keyword research and backlinks.
Update 08/2024 - This video is still getting a regular amount of views and I have questions once in a while on how to do something particular with the platform. These questions are good because they help me know what areas I need to focus on for the part 2 video, because my intentions originally were to focus more on the SEO aspects.
The site is working excellent and I plan to stay with the platform for the long haul. It looks great, loads fast, and works well for a lot of content. The initial setup is the hardest part of the process, and the maintenance and adding new content is straightforward. I've been working on a large update for the site as time allows for me to make the content. One thing I'll add to the main section is some more written instructions w/ photos for the trickier components of making your own site. In the replies to comments here, you can find answers for some of the issues you might be having in the process. If you'd like detailed help with troubleshooting, feel free to join my Discord server: discord.gg/AGJEe3xXC9 If I can see photos of your editor, it's much easier for me to know if there's formatting issues, which is something MkDocs is sensitive with.
Original comment below:
Here's the list of some of the commands followed by comments (noted with #, for those new to this, don't actually include # or anything after when trying to run commands) for those that want them. I will have a full write up on my new website sometime in the next few weeks to fill in any of the gaps from the documentation, with a more comprehensive list of code and commands.
To start, go to the main website folder you have and right click and select the terminal. Use the commands in the following order:
python -m venv venv # When using this command, you can change the second venv to create a folder name of your choice. I went with venv because it was easiest to use. You can use a different folder name by doing this: python -m venv foldername
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process # This is needed to let PowerShell run the script needed to launch the site.
venv\Scripts\Activate.ps1 # This launches the PowerShell script needed to start working on the site.
code . # If you're using VS Code as your editor, this will fire it up.
mkdocs serve # Put this in either the terminal window or in the VS Code terminal to serve the local version of your site. You'll need to see your site as you start making changes to make sure everything looks good after each save, since some changes may cause things to break and will need to be fixed right away.
:root {
--md-admonition-icon--youtube: url('data:image/svg+xml;charset=utf-8,')
}
.md-typeset .admonition.youtube,
.md-typeset details.youtube {
border-color: rgb(255, 0, 0);
}
.md-typeset .youtube > .admonition-title,
.md-typeset .youtube > summary {
background-color: rgba(255, 0, 0, 0.1);
}
.md-typeset .youtube > .admonition-title::before,
.md-typeset .youtube > summary::before {
background-color: rgb(255, 0, 0);
-webkit-mask-image: var(--md-admonition-icon--youtube);
mask-image: var(--md-admonition-icon--youtube);
}
# The above is the YT admonition I made. You can change this to whatever you want to make custom admonitions. To change the icon used, go to the MkDocs repo here: github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons Find the icon you want and click on it to pull up the photo. Look to the upper left and you'll see a tab called "code." That will give you that long ass path for the icon that you need to paste in like I did for the above example. If you try to use a simple path, i.e. icons/fontawesome/someicon, then it won't work.
The custom admonition code needs to go here: yoursitename/docs/stylesheets/extra.css You'll need to create the css file in whatever code editor you use. Then you can just paste and go.
{% extends "base.html" %}
{% block announce %}
You can follow me on
{% include ".icons/fontawesome/brands/twitter.svg" %}
Twitter
and
{% include ".icons/fontawesome/brands/youtube.svg" %}
TH-cam.
To see what has been updated on the website, refer to the
{% include ".icons/octicons/log-24.svg" %}
changelog.
Currently, the OPSEC section has been revamped for the release of the new site design.
The rework of the other sections is in progress.
{% endblock %}
# The above code is what I used to for the banner on the site. This needs to go in yoursitename/overrides/main.html Once again, just use your code editor to make the file.
Also, when you make changes and save to an HTML file, it won't show right away, at least when using VS Code. You'll need to click somewhere else in VS, like into a page that you're working on and save there (even if you haven't made any changes, this is just a weird glitch), then the HTML file changes will get saved so you can see the changes made in the browser window.
I'll add more detail to this when I make the site page tutorial. If you have any questions on this or anything else when making the site, please let me know. I'll be making a part 2 video in about a month.
Thanks for the great video. I learned a lot!
Something I forgot to add to the video - if you want to make a home landing page like how MkDocs Material has, you'll have to make one using HTML. This can get quite a lot more complicated than just using the docs part of the site. It wasn't the only reason I kept my main site separate from MkDocs, but it did have some factor. If you wanted to have more content that would be better served by using a different format than MkDocs, you could set it up where your other content is designed on a separate platform (i.e. Squarespace) and have direct links to the MkDocs section and use a subdomain.
Your tutorial is invaluable, thank you!
I'd love to see a video exploring the built-in Tags plugin, focusing on its non-sponsored features. Keep up the great work!
Thanks for supporting! I'll add that to the list for the follow up video. I'll also be adding some supplemental docs as well to help clarify setting some of this stuff up.
Thanks Ken another cool project to start with ^ ^
Great tutorial! How do you get the book icon next to "Knowledge Base" in the nav bar at the top of the page?
Thanks!
The icon there was actually not something I had intended to do - it just got placed there with how I set the site up.
I've got the main index.md file in the docs folder as the homepage. At the top of the page, I put icon:octicons/book-16.
Then in mkdocs.yml, I have my homepage nav set like this:
nav:
- Home: kenharris.io
- Knowledge Base:
- 'Start Here':
- 'Start Here': index.md
@@KenHarrisio Got it. Thanks Ken !
Cool video 😁 kindly for future python based repositories on github, do not commit virtual environment folder "venv" to github
Thanks for reminding me! That would have been an issue for anyone making a public repo. 😬 I'll make sure I add that to the part 2 video.
Thanks man. It was really helpful.
Would be nice if you put up the code and stuff somewhere, so I could just copy paste parts that I need.
:)
Sounds good, I'll swing back around a bit later and paste the code in. Is there anything in particular you were looking for or would you like all the custom sections that I made? Also, if there's anything else you'd like clarification on, please let me know. I'm going to start working on a part 2 for this soon to fill in the gaps that this video had.
Alright my man, I got that code pasted up in the pinned comment! If you have any questions, feel free to ask. I'm going to start working on the full write up sometime in the next few weeks.
pipenv is much easier to use than venv
Thanks for letting me know. I'll have a look at it.
@@KenHarrisio Like for example, pipenv install mkdocs, then it will automatically create a virtual env for you, while installing the packages only on the virtual env. Then after installation, you can just exec the command “pipenv run mkdocs serve”
I’ll also look forward seeing these in your future videos 😃
@@skyzane2735Damn, that's awesome! I'll give that a spin. Part 2 is probably a month or two away. Right now, I'm doing some SEO testing for the platform.
@@KenHarrisio Do you also have a video on how to test SEO for mkdocs or in general, please post video link 👏
@@skyzane2735 I'll actually be doing a couple SEO videos (none are on the channel yet). The first will be for MkDocs and the specific things that need to be done for it. I'm experimenting with a few different things on the platform to see what kind of differences it makes.
I'll also be making a general SEO video, which probably won't be until late May or sometime in June. Google is rolling out an update on May 5 to cut down on the amount of low quality content.
They didn't specifically say this, but it reads like anyone who has copy pasted anything from GPT is going to get their site deranked. Google is giving site owners a couple months to get this fixed. They also want to fix other quality issues. I.e. someone Googles a question and the answer needs to be 10 paragraphs to give a proper answer. Some sites will try to give a generic answer with one or two paragraphs but it didn't help the person at all. They are also penalizing content like that.
I want to see what happens to search after these changes roll out. I think it'll have a pretty sizeable impact on how people need to approach the content aspect of SEO. I read the info they released, and it sounds like the focus is going to be helpful (so generally in-depth) human made content.
It's looking like everything else should stay the same though, such as keyword research and backlinks.