Файлы Markdown (имена): есть «index.md» - обязательно?

Question

Это, очевидно, популярно, но ДОЛЖЕН «основной» файл в каталоге mkdocs называться index.md? Что делать, если я ссылаюсь на документы в папке с файлом, которая находится в другом месте, то есть не является частью иерархии этого файла? Я прошу, поскольку у меня небольшая проблема с связанными файлами, которые находятся в другом месте. Немного, если есть какая-либо документация об этом в сети, которую я нашел. Thx

Answer 1

Было выбрано имя файла index.md, так как настроено большинство (большинства) веб-серверов. Как правило, URL-адреса имеют две формы (в любом случае это относится к этой дискуссии). Они либо указывают на каталог, либо указывают на файл.

• /path/to/a/directory/
• /path/to/a/directory/with_a_file.html

общепринятого сконфигурировано поведение веб-сервера по умолчанию является то, что, когда он получает запрос на каталог, он будет служить файл index.html из этого каталога. В порядке слов, когда запрос сделан для /path/to/a/directory/, сервер вернет файл /path/to/a/directory/index.html.

Вместо того, чтобы изобретать это поведение с помощью другого соглашения об именах, MkDocs просто заимствовал такое же поведение. Когда вы «строите» свой сайт с помощью MkdDocs, файл по адресу /index.md построен до /index.html и будет обслуживаться сервером по адресу /. Теперь вы можете перенастроить сервер, чтобы обслуживать что-то другое, когда запрашивается каталог, но существующая система существует уже столько лет, что редко имеет смысл сделать это.

Таким образом, если вы создаете ссылки в своих документах на страницу, находящуюся в каталоге, ссылайтесь непосредственно на эту страницу: /path/to/some/page.html. Однако, если вы ссылаетесь на «главную» страницу в каталоге, обратитесь к самому каталогу: /path/to/a/directory/ и страница в /path/to/a/directory/index.html будет подана.

Единственное дополнительное соображение, о котором вы должны знать, это то, что MkDocs делает это еще проще. Вам не нужно знать, к какому пути будет создан файл. Если вы ссылаетесь на файл Markdown, MkDocs выполнит «правильную вещь» и перепишет ссылку, чтобы указать на встроенный HTML-файл, как documented. Так что ссылку на some/page.md и он перепишет ссылку для вас на some/page.html или some/page/, в зависимости от того, как у вас есть use_directory_urls настройка настроена. Обратите внимание, что когда параметр use_directory_urls равен true (по умолчанию), MkDocs использовал трюк «индекс», помещая каждый файл в свой собственный каталог в качестве индексного файла, поэтому никакие расширения файлов никогда не используются. Однако, если вы используете внутренние ссылки .md, ссылки будут генерироваться правильно.

С перепиской с вами возникает вопрос, что, возможно, вы пытаетесь связаться с документами за пределами сайта MkDocs. Однако неясно, подразумеваете ли вы документы, размещенные на одном сайте или размещенные на других сайтах. Поэтому я расскажу об обоих.

Для документов, размещенных на других сайтах, просто укажите весь адрес, включая хост. Лично я часто перехожу на страницу в свой браузер, а затем выбираю адрес в адресной строке и копирую все это в свой документ. Например, ссылка, приведенная в документации MkdDocs, была http://www.mkdocs.org/user-guide/writing-your-docs/#linking-documents, поэтому я скопировал все это в этот ответ как URL-адрес ссылки.

Если вы запрашиваете ссылку на другие документы внутри одного и того же хоста, это зависит от вашей конфигурации.Например, если у вас есть несколько вещей, обслуживаемых бок о бок, где у вас есть документы по адресу http://example.com/foo/, с которым вы хотите ссылаться, с вашего сайта MkDocs, который подается от http://example.com/bar/, тогда вы можете использовать полные ссылки, например, с внешними сайтами, или вы можете использовать относительные URL-адреса, как описано в моем ответе на ваш вопрос: Markdown: referencing directories outside of a document's path (“peer” folders). Возможно, с лучшим пониманием того, как работают «индексные» страницы, вы сможете лучше создавать относительные ссылки.

Если, с другой стороны, вы хотите ссылаться на файлы, которые находятся за пределами корня документа, ну, вы не можете. Любой веб-сервер, который я видел, настроен на повышение ошибки в качестве меры предосторожности и не будет обслуживать файлы, находящиеся за пределами корневого каталога сервера. Если вы хотите обслуживать файл, и вы не можете удалить его из своего местоположения за пределами корневого сервера, вам необходимо будет его скопировать или создать ссылку на него в файловой системе. Тем не менее, в зависимости от того, как настроен ваш сервер, ссылка на уровне ОС может или не может быть успешной. Однако это будет предметом другого вопроса.