[Request] Step-by-step guide for custom home screen

[Skrillx13]

i managed to follow a random discussion on how to get a home screen but i am not sure how to progress from here. I know you can add images and such through the home.html file but i am unsure how to integrate it like squidfunk did. Can someone like make a step by step guide for this? Apologies I am really bad at stuff like this, any and all help is greatly appreaciated. Thank you

[alexvoss]

It would depend on what you need, which is the problem with a step-by-step guide. There would be too many variations. If there is anything more specific that you need to do and don't know how to please do follow up with a specific question and we can try to help. Please state what you want to achieve and what you have tried.

As to the homepage for Material for MkDocs, a lot of effort has gone into this, especially the parallax effect that provides the animation when scrolling. It is not something that can be made easy.

[Skrillx13]

i just want something like the image, and the rest of the features below. The smooth animation is not necesary. Also i noticed that squid funk actually has documentation for this. In his page tree, there is a "adding-a-landing-page.md" file, and maybe that can also be of use?

[alexvoss]

I am sorry but can you please provide context to things you say? I have the sources for the documentation checked out and I cannot find this page, double-checked on GitHub. Where did you see this?

[Skrillx13]

mkdocs-material/mkdocs.yml

Line 169 in 0067197

#- Adding a landing page: setup/adding-a-landing-page.md

In the page tree part

[kamilkrzyskow]

That's a commit from 4 years ago.
Doing a check with:

git log --follow docs/setup/adding-a-landing-page.md

reveals that the file never existed 🤔

[Skrillx13]

oh it was just a commit message. my bad for misclarity

[squidfunk]

We're working hard in the background to make many things simpler, including layout customization and creation of landing pages. Looking back, it might not have been the best idea to create such a complex landing page without users being able to easily replicate it. Regardless, as said, we're working on providing more templates and easier customization in the future.

[Skrillx13]

Alright thanks good to have some assurance that layout is becoming easier. Great work on maintaining the project squid funk, all the best

[kamilkrzyskow]

Hi @Skrillx13,
I changed the category and the title of the discussion, as this is not a question with a definite answer.
I'm probably breaking some decorum about handling Insiders, but I think this has to be said.

Even though the raw source code of the parallax implementation is in the Insiders repository:

• https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/overrides/home.html
  so if you want to access it you need to become a sponsor

as the functionality is fully front-facing, the minified source code is public in our web browsers.

JavaScript files are minified, with variable name changes, so it's hard to extend it, but I did a quick test to check if turning off JavaScript would break the effect.
It didn't, so no JavaScript knowledge is required.

The page loads custom and home stylesheets, and I checked if blocking custom would break the effect.
It didn't, so only the home CSS is required.

Screenshot

---

So given the above, if I would want to hack it without access to Insiders, I would...:

1. Copy the HTML source code of the homepage.
   Make it more readable using a formatter tool.
2. Paste the HTML into the home.html template, without any extends "base.html" part.
3. Download the home CSS file.
   Make it more readable using formatter tool.
4. Place the home CSS file in the correct directory, to match the path inside the HTML source.
5. Attach the custom home.html template to the index.md file.
   https://squidfunk.github.io/mkdocs-material/reference/#setting-the-page-template
6. Open up the page and web dev tools.
7. Fix all issues along the way, like missing images (errors in web dev tools), and read the home.html code from top to bottom removing/replacing unnecessary parts of the code (like analytics, or other content specific to Material for MkDocs).
8. Watch 3+ YT tutorials about the parallax effect, as I don't know much about it:
   https://www.youtube.com/results?search_query=css+parallax
9. Implement the new knowledge from the tutorials to adjust the home CSS file.

Once it's all finished and somewhat working, I would generalize the home.html into a true template, using {{ config.site_name }} etc. to match the settings in the mkdocs.yml file.

All of the above steps, could have 3+ steps in-between, especially 7. and 9., so as you see making a step-by-step guide applicable to everyone is just not feasible. But if you do decide to make your own parallax implementation, then be sure to document it and share ✌️

[squidfunk]

Currently no timeline, as we're working on much bigger things right now, see our latest blog post.

[A3Bagged]

2. Paste the HTML into the home.html template, without any extends "base.html" part.

What exactly do you mean by this? Do i need to paste the whole html form material page in home.html template file? Or do i need to strip it down? And im not sure what you mean by without any extends bate.html part

PS: what's that browser inspector? I like it, with the default opera gx one i cant seem to disable css

[kamilkrzyskow]

@A3Bagged
Hey, thanks for trying to follow along the "guide" 😃

Do I need to paste the whole html from material page in home.html template file?

Initially, yes. The idea is to copy a working source code into your docs, and then step by step, through error fixing, adjust it to your liking.

Or do i need to strip it down?

This comes later in step ~7, while fixing issues, you can as well remove irrelevant parts.

what you mean by without any extends base.html part

The default template for all of the docs pages (Markdown files) is the main.html and by default it only extends (so in other terms loads) the base.html template. Using theme extension you can overwrite the main.html file and override blocks provided in base.html.

• The source version of the base.html contains comments:
  • https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/base.html

The idea is that you initially copy the raw HTML from the browser inspector or view-source: view and manually turn it into a Jinja2 template adjusted to your docs. You can add the extends part later and focus on block overrides, however this should come later once the initial parallax code is working.

what's that browser inspector? I like it, with the default opera gx one i cant seem to disable css

Firefox 🔥 🦊 😎 I haven't used Opera GX, but Thorium (also Chromium-based) supports the "Block request from URL" inside the Network tab. First you need to load the page and see the requests, then right click and select to block it from the context menu.

---

If you don't want to use the parallax effect and just want a slightly custom home page, then you don't have to go through the whole process.

You can start off with block overrides like shown in the example here:

• https://squidfunk.github.io/mkdocs-material/customization/#overriding-blocks
• https://github.com/squidfunk/mkdocs-material/blob/master/material/overrides/home.html

Or you can put custom HTML into the Markdown file itself, combined with the md_in_html extension there is a lot you can do, but mind that formatting is very strict when doing so. A example can be seen here on the Nype brand page:

• https://github.com/nypesap/nypesap.github.io/blob/main/docs/index.md
• https://github.com/nypesap/nypesap.github.io/blob/main/overrides/home.html

[A3Bagged]

@kamilkrzyskow
Thanks for the quick reply! Meanwhile i've got it working.
All that's left to do is part 7 and then customize it so it's not a "copy" anymore 👍

---

Thank's for the detailed explanation about extends, i could find a little on google (about a basic base.html file)
I've gotten theblocking CSS done in inspector (which both Opera & Chrome use "DevTools" works a little different but you essentially block the Url. For Javascript i simple downloaded a JS blocker extension for Opera.

[kamilkrzyskow]

The blocking of JavaScript and other CSS files was only necessary to pinpoint which files are needed to get it working, it's not required for following the guide 🤔 . Also both Firefox and Chrom Dev Tools allow to block JavaScript via the extended options. Look for a "settings gear" ⚙️ icon perhaps hidden in some "triple dot / hamburger" menu, and there should be an option to reload the given page without JavaScript.