Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Title doubles #1374

Closed
Serhioromano opened this issue Jan 8, 2018 · 9 comments
Closed

Title doubles #1374

Serhioromano opened this issue Jan 8, 2018 · 9 comments

Comments

@Serhioromano
Copy link

@Serhioromano Serhioromano commented Jan 8, 2018

I have a file in subdirectory. Let's say I call it ACL.md. In config it is used like this

pages:
- Developer:
    - ACL: ACL.md

The file starts with H1 tag and then other titles like a structure. The H1 title is the same meaning as the title in config file. So in navigation title doubles and create unnecessary level. I have only one H1 per file.

Is it possible to tell mkdocs not to use first H1 in menu navigation? I have a screenshot, not sure if it is helpfull because it is on russian.

2018-01-08_13-24-05

1 - is a title in configuration

- Метод API: 'developer/apiendpoint.md'

2 and 3 is H1 title in the document. how to avoid this?

@algo99
Copy link

@algo99 algo99 commented Jan 8, 2018

++
Looks like feature request for me as well.

We solve this though not using H1 headers in our index.md files.

@waylan
Copy link
Member

@waylan waylan commented Jan 8, 2018

At this time there is no builtin way to account for this. However, you might be able to address this through theme customization. I haven't looked at the template, not sure if it would be a simple fix or not.

@squidfunk
Copy link
Contributor

@squidfunk squidfunk commented Feb 12, 2018

Material uses a hack to determine if a h1 is included in the Markdown source, see:

https://github.com/squidfunk/mkdocs-material/blob/5bc0875e7e3bb5edfb984a516b22cc74acb5d257/src/partials/toc.html#L29-L37

@waylan
Copy link
Member

@waylan waylan commented Feb 12, 2018

@squidfunk interesting approach. Not sure how that it supposed to work in the layout for the readthedocs theme though. We would then have children with no parent. I suspect the right approach would be to skip/exclude the child link to the h1. The parent link to the "page" would get you there anyway.

@squidfunk
Copy link
Contributor

@squidfunk squidfunk commented Feb 12, 2018

This hack has been in Material for a long, long time and it works reasonably well. It just kills the first layer of TOC if it is an h1, but it also assumes that there is only one h1 per document, which is semantically correct.

However, just wanted to let you know how I solved the problem.

@Serhioromano
Copy link
Author

@Serhioromano Serhioromano commented Mar 4, 2018

@squidfunk Of course it is solvable with hack. i can override navigation file and exclude that. But that way I rather solve my own problem but not the problem itself.

On the other hand Python is not my strongest side. If it would be PHP or JS, I would create PR instead of issue.

@cjsheets
Copy link

@cjsheets cjsheets commented Mar 5, 2018

Unfortunately, the rtd-dropdown theme doesn't gracefully support all doc structures at the moment. Thanks for referencing the issue @Serhioromano.

I'm almost done cleaning up the initial implementation and adding configuration options to extend support to additional doc structures.

Because MkDocs is pretty flexible, users will probably still need to pick a convention and stick to it. I'll improve the Readme to clarify what configurations are supported to create the nested effect.

Thanks for referencing the technique used in Material @squidfunk. After some testing I think I'll need to do something similar. I'll have to make it a configurable option though because the ReadTheDocs convention is to have multiple H1 tags per page and make the TOC collapse at each one.

@squidfunk
Copy link
Contributor

@squidfunk squidfunk commented Mar 5, 2018

because the ReadTheDocs convention is to have multiple H1 tags per page

Correct me, but from my knowledge that's semantically incorrect HTML, except when those headlines are enclosed in separate article tags.

@Serhioromano
Copy link
Author

@Serhioromano Serhioromano commented Mar 5, 2018

@cjsheets thanks for being so responsive.

If there are few H! tags per document it is logical to use those as collapsable in menu. it mean that user user H1 tags to create sections of the document.

I use H1 tag to create a single title of the document. I think it is logical that user see the same title as menu link used to be, on which he clicked. Also the point of MkDocs to use markdown as text, in my opinion is to have readable base. So even if website is not generated, documents are automatically readable for example though github document preview. So the H1 title in the document become very important.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants