mkdocs导航标题与页标题不同

Question

我的mkdocs.yml文件中的nav标题被缩短为只适合左侧导航中的一行，并且我希望.md标记页面标题是未缩略的完整标题。

例如，虽然我的mkdocs.yml文件包含：

nav:
- BD, ML, DS: Big_Data,_Machine_Learning,_Data_Science.md
- AI, VI: Artificial_Intelligence,_Video_Intelligence.md

我希望.md页面标题是：

Big Data, Machine Learning, and Data Science

复制/使用...instead导航标题的mkdocs.yml：

BD, ML, DS

当我将Markdown页面标题添加到我的.md文件的第一行(.md)时，我得到了我想要的页面标题和继承的mkdocs.yml nav标题：

BD, ML, DS
7 min (1,939 words)
Big Data, Machine Learning, and Data Science

答案似乎是在mkdocs.yml文件中指定一个不同的/秒“页面显示”名称，但许多谷歌搜索都没有发现任何内容。

你还试过或听说过什么其他方法？谢谢!

Answer 1

这是唯一可能的自定义主题，它特别增加了对这样一个功能的支持。然而，我不知道有任何主题提供这样的特点。

页面只能有一个标题。但是，页面标题可以以以下四种方式之一定义为记录在案

MkDocs将尝试以下列方式确定文档的标题：

1. 在文档的导航配置设置中定义的标题。
2. 在文档的title元数据键中定义的标题。
3. 文档正文第一行的一级标记头。
4. 文档的文件名。

在找到页面的标题后，MkDoc将不再继续检查上面列表中的任何其他源。

最后一句是成功的关键。由于MkDocs正在找到在mkdocs.yml配置文件的nav配置中定义的title，因此它从不检查在其他地方定义的title (包括元数据)。它只使用页面的nav标题作为页面标题(在page.title属性中)。

但是，页面的元数据仍然保存在page.meta属性下。因此，您可以在自定义主题的page.title部分中使用nav，在主题中的任何地方都可以使用page.meta.title。

若要定义页面的元数据，请将YAML部分添加到Markdown文件的开头：

---
title: Big Data, Machine Learning, and Data Science
---

The first line of your Markdown.

当然，像前面一样，在配置文件中定义一个标题：

nav:
- 'BD, ML, DS': 'Big_Data,_Machine_Learning,_Data_Science.md'

然后，在主题中，您可以使用page.title (您希望BD, ML, DS出现的位置)和page.meta.title (您希望Big Data, Machine Learning, and Data Science出现的位置)。

如果您不想从头开始创建一个全新的主题，那么您可以使用合并 目录和模板块来覆盖所选主题的特定部分。

Answer 2

我也会使用元数据，但与Waylan建议的方法略有不同。

Waylan建议使用：

• 配置文件中的nav条目- 'Short Title': file.md；
• 元数据title: Long Title位于Markdown文件的顶部。

我建议只依赖页面元数据：

• 元数据short_title: Short Title位于Markdown文件的顶部；
• 元数据title: Long Title位于Markdown文件的顶部。

我认为这个计划有两个好处。

1. 您不会破坏XXX.title的内置语义:它仍然意味着完整的标题。因此，与其修补主题中对它的每一次使用(并打破您遗漏的部分)，您只需要修补要使用简短标题(大概只有导航菜单)的部分，以XXX.meta.short_title替换任何出现的XXX.meta.short_title。
2. 我认为一页的标题(短或长)是其内容的一部分。它是本页的本地内容。因此，我不喜欢将内容分散到本地Markdown文件和中央配置文件之间，也不需要手动保持两者的同步(并且在某些时候不能做到)。元数据-嵌入在Markdown文件开头的数据支持纯本地版本。我可以让MkDocs只从我的Markdown文件中生成nav菜单，而不会在全局配置文件中复制数据。

或者更确切地说是XXX.meta.short_title if (XXX.meta is defined and XXX.meta.short_title is defined) else XXX.title。