[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 ✌️

[Skrillx13]

Alright thanks. This was what I was kinda looking for but apparently navigation and landing pages are being worked on so hopefully it's easier in the future. Appreciate the help though

[kamilkrzyskow]

I'm assuming the easier implementation won't get released for the next couple of weeks/months, it's not going to be tomorrow 😅, so in that time you could likely get a working customization going and learn some CSS which will always be a relevant skill.

[squidfunk]

That's correct, we still need a lot of work to finish. Thanks for providing the instructions!

[itaysk]

won't get released for the next couple of weeks/months

we still need a lot of work to finish

I want to create a docs site with a homepage similar to mkdocs-material's, I can delay this project by by a few weeks if it will save me work. I wanted to confirm, what exactly is being worked on and if there's a timeline to expect. I should note I am using insiders.

[squidfunk]

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