Steps to creating a similar homepage

[asriley]

Hello,

Firstly thank you all for the contributions! This theme really is amazing and elegant!

I have been trying to follow the code here: https://github.com/squidfunk/mkdocs-material/blob/master/material/base.html for creating my own homepage on my material themed mkdocs site. However, the auto-generated nature of the base.html, index.html and home.html leave me wondering if I can actually do this after a few failed attempts now.

I have used these sources: https://www.mkdocs.org/user-guide/styling-your-docs/ and https://squidfunk.github.io/mkdocs-material/customization/.

However, neither source (nor them together) actually really inform me about how to extend my current index.md file to be something like this: https://squidfunk.github.io/mkdocs-material/.

I can find nothing about this on youtube or within search engines. Just not sure what steps to take to create my own index.md as a nice templated homepage...

Misc Info: Mkdocs version: mkdocs, version 1.1.2 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8) My project is hosted on bitbucket and not github. I am not a web developer.

Any help will be appreciated.

[squidfunk]

This is something I've wanted to add some documentation on, but haven't had the time yet. I'll leave this open as a reminder when there's some time for lower priority stuff 😊

[asriley]

Martin,

That would be great! I like using mkdocs but one of the setbacks is that it doesnt seem easy to create a homepage that is unlike the other pages. Will be looking forward to it! Let me know if there is any way I can help! Would love to if possible.

[tmeuze]

@asriley This is the file you are looking for: overrides/home.html. You'll want to copy it over to your own overrides directory. Make sure you've set your custom_dir in mkdocs.yml:

theme:
  custom_dir: docs/overrides
...

In the front matter of your index.md, you need to specify the template to use:

---
title: Title
template: home.html
---

One important thing that took me a while to realize: you need a newline at the end of your md file. If you don't have one, the content will not display. I guess it's processed as having null content if you don't include the newline.

[Guts]

You can also have a look to others website like UP42:

Source: https://github.com/up42/up42-py

Ping @Arnaud-UP42 and @chrieke.

[squidfunk]

So, in the end, I decided to close this issue, as enough guidance should've been given by https://github.com/squidfunk/mkdocs-material/issues/1996#issuecomment-718247120 – it all boils down to using a custom template for a specific page, as noted in the comment, and providing the implementation for this template.

[exequielrafaela]

Thanks for all your feedback here, it was really useful for us too 🙏🏼 💯 👏🏼

As a gesture of gratitude we add our 2 cents:

• ✅ ⛵ | Binbash Leverage - Example
• ✅ 👨🏼‍💻 | Source
• ✅❓ | StackOverflow Q

[asriley]

@tmeuze

@asriley This is the file you are looking for: overrides/home.html. You'll want to copy it over to your own overrides directory. Make sure you've set your custom_dir in mkdocs.yml:

theme:
  custom_dir: docs/overrides
...

In the front matter of your index.md, you need to specify the template to use:

---
title: Title
template: home.html
---

One important thing that took me a while to realize: you need a newline at the end of your md file. If you don't have one, the content will not display. I guess it's processed as having null content if you don't include the newline.

Hello, wow I did not realize there was a reply here! I am following your exact suggestions - but am getting this error:

I added both a main.html and home.html to the overrides directory (just copied and pasted from material's site to try to get past this error but no luck). Additionally I added a main.html file in my docs directory as I see alot of other people have done that. I think there are still some missing steps. For example:

1. @exequielrafaela 's custom_dir is material and not the overrided directory. Not sure why it was changed and still works.
2. Also, a lot of these pages are "autogenerated". Therefore, I am confused about what should be done to "generate" these auto pages? (base.html, main.html, etc...) Will "mkdocs serve" cause this to happen?

Just using squid's home.html and main.html until I get past this error.

[exequielrafaela]

@asriley In my case it still works because I declare that in the mkdocs.yml as follows:

theme:
  name: material
  custom_dir: material

Consider that the overrides folder is already implicitly declared since (I understand) is the default name it looks for in the custom_dir. So you can use any directory as long as it's properly declared in your mkdocs.yml

I've followed @tmeuze instructions and everything worked as expected. And dont's forget to check this 👇🏼

You need a newline at the end of your md file. If you don't have one, the content will not display. I guess it's processed as having null content if you don't include the newline.

[chrimaho]

Hi @squidfunk,

Love the library! Thanks!

I've been able to follow the instructions on this issue, and can successfully implement a home page for my site. Thanks!

Even so, I still think that there is value in adding a page to your master docs (like you mentioned here). If I can draft up some changes and push it to you as a Pull Request, would you still consider it as a possible addition to your site?

Just thinking out aloud, it may include some changes such as:

• Some (super basic) HTML templates in the .overrides directory
• Maybe a new HTML variable to pull through the site_name and site_description from the mkdocs.yml file and render it on the HTML template.

Before I commence working on this, I just wanted to check to see what you think?

Thanks!

- Chris M

[squidfunk]

@chrimaho I'm currently not considering adding demo customizations to the repository. We've started building a new repository with examples, which is where such things should live. It's not ready yet, but it will contain examples for all (?) features from the documentation, which can also include customizations.

When ready, we'll also add links from the docs for each feature.

[chrimaho]

Sounds like a plan. Thanks! 👍

[valhuber]

@squidfunk

I share the interest in creating a landing / hero unit page, as discussed here. I am uncertain whether your intent to publish a new repo with examples will include this...?

On this page, a file often cited is https://github.com/squidfunk/mkdocs-material/blob/master/material/overrides/home.html, but it's gone. That makes me uncertain whether to plow through this to try to get a landing hero.

On this page, it appears that the expectation is that to get a landing-hero you need to become a sponsor. Is that correct?

[squidfunk]

The source code of the landing page cannot be released due to licensing restrictions. Thus, yes, you would need to become a sponsor if you would want the source code of our own landing page. I'm sorry, but there's no way around this. Other than that, we'll consider providing additional landing page templates in the future.

[squidfunk]

FWIW, our old landing page is here (overrides was renamed to .overrides at some point): https://github.com/squidfunk/mkdocs-material/blob/master/src/.overrides/home.html

[tylerdotrar]

If there's anyone still struggling with this, I made a fairly simple and straightforward template based on the up42-py project (as pointed out in @Guts comment ) that also supports modification via the mkdocs.yml configuration file.

Project found here: https://github.com/tylerdotrar/mkdocs-coverpage

• The style won't be to everyone's taste, but it should at least be a decent enough baseline for customization.

[Guts]

Thanks @tylerdotrar for sharing and making a customizable homepage :clap:

[valhuber]

Let me add my thanks to @tylerdotrar as well.

This works fine. but is there a way to have markdown content follow the banner? I see you can add html, but I have quite a lot of md content I want to add...

[gabrielbdornas]

This works fine. but is there a way to have markdown content follow the banner? I see you can add html, but I have quite a lot of md content I want to add...

@valhuber have you found the answer to this question?

I'm using the @tmeuze suggestion, but with {{ super() }} inside the {% block content %}{% endblock %}.

So, my home.html page looks like:

{#-
  This file was automatically generated - do not edit
-#}
{% extends "main.html" %}
{% block tabs %}
  {{ super() }}
  <style>.md-header{position:initial}.md-main__inner{margin:0}.md-content{display:none}@media screen and (min-width:60em){.md-sidebar--secondary{display:none}}@media screen and (min-width:76.25em){.md-sidebar--primary{display:none}}</style>
  <section class="mdx-container">
    <div class="md-grid md-typeset">
      <div class="mdx-hero">
        <div class="mdx-hero__image">
          <img src="assets/images/illustration.png" alt="" width="1659" height="1200" draggable="false">
        </div>
        <div class="mdx-hero__content">
          <h1>Technical documentation that just works</h1>
          <p>{{ config.site_description }}. Set up in 5 minutes.</p>
          <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | e }}" class="md-button md-button--primary">
            Quick start
          </a>
          <a href="{{ 'insiders/' | url }}" title="Material for MkDocs Insiders" class="md-button">
            Get Insiders
          </a>
        </div>
      </div>
    </div>
  </section>
{% endblock %}

{% block content %}
{{ super() }}
{% endblock %}

{% block footer %}{% endblock %}

[horizon365]

FWIW, our old landing page is here (overrides was renamed to .overrides at some point): https://github.com/squidfunk/mkdocs-material/blob/master/src/.overrides/home.html

can't open it. 404 - page not found

[squidfunk]

@horizon365 we've redone our home page. The overrides are currently hosted in Insiders. Also see:

• https://github.com/squidfunk/mkdocs-material/discussions/7390