Interesting behaviour with Page icons

[Andre601]

I've noticed a interesting behaviour with page icons. This being that a page icon won't be displayed within a Nav tab, even if it was the only page within said tab.
Only when turning this page into a index page, putting it into a folder and then define it in the nav will it work.

Is there a way to display the page icon within the nav, even when the page itself isn't an index page for that tab?

Here's a mkdocs.yml nav setup I have:

nav:
  - Home: 
    - index.md # Displays icon in Nav tabs
    - commands.md
  - Profiles:
    - profiles/index.md # Displays icon in Nav tabs
    - Formatting: profiles/formatting.md
    - Placeholders: profiles/placeholders.md
  - API:
    - api/index.md # Displays icon in Nav tabs
    - Changelog: api/changelog.md
  - Examples: examples.md # Won't display icon. Only "Examples: examples/index.md" will.
  - PlaceholderAPI: placeholderapi.md # Won't display icon. Only "Examples: placeholderapi/index.md" will.

[DrVrej]

I am having this issue as well

[alexvoss]

Putting the Markdown file into a folder and calling it index.md does not work for you? Seems like a sensible workaround to me. I am not sure the tabs were ever meant to work for anything other than sections. Note what the description for the navigation.tabs feature says.

[DrVrej]

Yup that would be the simplest solution, was hoping maybe there is a way around it to keep my files organized the way it is right now, thank you for the help though!

[kamilkrzyskow]

If the old file structure preservation is a must, then you could use this "hack" @DrVrej, and have both the other/index.md file and the other.md.

site_name: My Docs
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.indexes

nav:
  - Home:
    - index.md
  - Other:
    - other/index.md

not_in_nav: |
  other.md

markdown_extensions:
  - pymdownx.snippets

To not duplicate content use Snippets or the macro plugin should also work. There are some limitations, concerning order of execution, but if you run into them then it would be better to use the default approach or setup a custom one with hooks etc..

other/index.md

--8<-- "docs/other.md"

---

example-with-snippets.zip

[DrVrej]

@kamilkrzyskow Thank you for the reply! I had thought of doing that using macros, though it does leave one issue: Say we have a page (about.md) and it's located inside the docs folder alongside the main index.md, and so the URL would be example.com/about however once we move it to a folder so the icon can show up, say it's named folder1, then the URL becomes example.com/folder1/about. Is there a way to edit what the URL is going to be of a page? Thank you!

[kamilkrzyskow]

If you put the file into a folder don't keep the about.md name, just rename it to index.md.
Both about.md and about/index.md result in the same final about/index.html rendered static file.
This is caused by this setting: https://www.mkdocs.org/user-guide/configuration/#use_directory_urls

As for URL changing, this is the custom approach with hooks, you could change URL inside the on_files event:
Example from the blog plugin

mkdocs-material/src/plugins/blog/plugin.py

Lines 124 to 128 in 9ec2ee0

	# We need to adjust destination paths for assets to remove the
	# purely functional posts directory prefix when building
	file.dest_uri = file.dest_uri.replace(path, root)
	file.abs_dest_path = os.path.join(site, file.dest_path)
	file.url = file.url.replace(path, root)

Also please note that MkDocs doesn't detect URL collisions automatically, and neither the Blog plugin is doing it.
So either implement URL duplicate detection or be very cautious when "playing around" with URLs 🙂