readthedocs

[montyvesselinov]

I am trying to use the material theme on readthedocs. I was able to install it; but i still cannot get the material theme up; i get only the default. Any suggestions how to fix this?

[squidfunk]

Uh, I have absolutely no experience with getting it on RTD. If you find out, please write a step-by-step instruction, so we can add it to the documentation and everybody can benefit. Is it even possible? Does it state so in the documentation?

[squidfunk]

BTW: you can host on GitHub Pages. MkDocs supports this out-of-the-box. The Material documentation itself is hosted on GitHub Pages.

See: http://www.mkdocs.org/user-guide/deploying-your-docs/#github-pages

[montyvesselinov]

It works on github:

http://madsjulia.github.io/Mads.jl

But i also wanted to have it on RTD.

I like very much the material theme.

[squidfunk]

Hmm, I think this is a general issue with readthedocs. You should ask your question in regard to using custom themes in general here:
https://github.com/rtfd/readthedocs.org

I'm afraid I can't help you, but please tell us when you managed to do it. I will close this issue for now.

[brianjking]

@montyvesselinov @squidfunk AFAIK you have to use the ReadTheDocs theme when hosting on readthedocs.org. You can customize that theme, at least you can when using Sphinx (instead of MkDocs), however, as per the MkDocs documentation it seems you may be stuck: https://github.com/mkdocs/mkdocs/blob/master/docs/user-guide/deploying-your-docs.md#read-the-docs

[brianjking]

@montyvesselinov readthedocs/readthedocs.org#978 read this though...

[israteneda]

I was able to install the mkdocs-material theme in RTD. Before to start, the docs of my project are in /docs of my GitHub project. If your case is similar, you can continue with the next steps:

1. Create a requirements.txt file in /docs with mkdocs-material dependency:

mkdocs-material

Next files are in the root directory

2. Create mkdocs.yml file to use mkdocs-material theme:

site_name: <site_name>
theme:
  name: material

3. Create a readthedocs.yml file with the config to install dependencies and use mkdocs configuration:

version: 2

python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt

mkdocs:
 configuration: mkdocs.yml

This is the final structure

[kmjungersen]

Thanks @israteneda !

For anyone else might come across this, here's the page on docs.readthedocs.io describing this. It definitely wasn't immediately apparent to me.

[TomTranter]

This didn't work for me. I also had to add 'docs_dir: docs' to mkdocs.yml

[johnkerl]

whew!!! thanks @israteneda!!! finding this saved my day!!! :)

a fresh update, maybe something has changed with
https://docs.readthedocs.io/en/stable/config-file/v2.html#python-version
-- I found that their stanza

python:
  version: "3.7"
  install:
    - requirements: docs/requirements.txt
    - requirements: requirements.txt

got me a red error box with

Problem in your project's configuration.
Invalid "python.version": .readthedocs.yaml: Invalid configuration option: python.version.
Make sure the key name is correct.

what i used today was this mkdocs.yml:

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-20.04
  tools:
    python: "3.8"

python:
  install:
    - requirements: docs/requirements.txt

mkdocs:
  configuration: docs/mkdocs.yml

where my docs/requirements.txt has (as above, no change)

mkdocs-material

[swills1]

I realize this is old, but I just went through and figured out how to make this work as of 2023-11-18.

I forked the Acme repo above and made some changes to bring it up to date.

1. Remove readthedocs.yml
2. Add .readthedocs.yaml - changed Ubuntu version to latest and set Python version to the min supported (3.8)

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.8"

python:
  install:
    - requirements: docs/requirements.txt

mkdocs:
  configuration: mkdocs.yml

3. Adjusted mkdocs.yml to add the Repo info to the right of the sidebar, and changed the palette to make sure it worked. Both did which was awesome. I had the color palette I chose and my repo info showed to the right of the sidebar.

site_name: Test
theme:
  name: material
  palette: 
    primary: deep orange
repo_url: https://github.com/swills1/acme
repo_name: Acme
nav:
    - Quickstart: 'index.md'
    - Problem Description: 'problem.md'
    - Architecture: 'architecture.md'
    - Approach & Methodology: 'approach_methodology.md'
    - Install Manually: 'install_manually.md'

My requirements.txt had one line / one requirement mkdocs-material.

I tried to get the light / dark theme toggle to work, but realized that was an insider feature. I use the Dark Reader Extension in my browser and I'm sure a lot of others do as well. So not a big deal. (I'd support, but the support is a recurring monthly cost. I can't afford $180 a year for libraries I am putting out for free. But would be more than willing to do a one time donation.)

Too long, didn't read - this works as of November 2023.