From 625e423b76efbf3c67fc2169190c3dd204c86e12 Mon Sep 17 00:00:00 2001 From: Dan Untenzu Date: Tue, 13 Aug 2019 09:04:02 +0200 Subject: [PATCH] Docs: Clarify page title generation --- docs/user-guide/configuration.md | 5 +++-- docs/user-guide/writing-your-docs.md | 6 +++--- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 8ecdb72a..f5dfd827 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -182,7 +182,8 @@ including how to create sub-sections. Navigation items may also include links to external sites. While titles are optional for internal links, they are required for external links. An external link may be a full URL or a relative URL. Any path which is not found in the -files is assumed to be an external link. +files is assumed to be an external link. See the section about [Meta-Data] on +how MkDocs determines the page title of a document. ```yaml nav: @@ -217,7 +218,7 @@ server root and effectively points to `https://example.com/bugs/`. Of course, th **default**: By default `nav` will contain an alphanumerically sorted, nested list of all the Markdown files found within the `docs_dir` and its -sub-directories. If none are found it will be `[]` (an empty list). +sub-directories. Index files will always be listed first within a sub-section. ## Build directories diff --git a/docs/user-guide/writing-your-docs.md b/docs/user-guide/writing-your-docs.md index 665fdd99..2ac265d8 100644 --- a/docs/user-guide/writing-your-docs.md +++ b/docs/user-guide/writing-your-docs.md @@ -111,9 +111,9 @@ source files for the above configuration would be located at `docs/index.md` and `docs/about.md`. The above example will result in two navigation items being created at the top -level and with their titles inferred from the contents of the file (or the -filename if no title is defined within the file). To define a custom title for -the pages, the title can be added before the filename. +level and with their titles inferred from the contents of the Markdown file or, +if no title is defined within the file, of the file name. To override the title +in the `nav` setting add a title right before the filename. ```no-highlight nav: