Ссылка на внешний файл yml, где взять

Обновлено: 21.11.2024

Структура вашей книги определяется содержанием. Это файл YAML (называемый _toc.yml ), определяющий структуру, которую Jupyter Book использует для создания порядка и вложения страниц.

Перейти к новой структуре оглавления

В версии 0.11 появилась новая структура оглавления. Чтобы перенести старую структуру TOC на новую структуру, у вас есть несколько вариантов:

Вручную перенесите оглавление. См. эту запись в блоге для одного примера миграции из старой структуры TOC.

Используйте инструмент миграции. Это автоматически сгенерирует новое оглавление из вашего старого, хотя может немного изменить форматирование. Для этого используйте следующую команду:

Структура книги¶

Оглавление в общих чертах организовано следующим образом:

Вот краткое описание каждой клавиши:

Определяет структуру этого оглавления (например, как интерпретировать названия ключей). jb-book указывает Jupyter Book ожидать терминологию глав и частей (подробности см. ниже).

Первая страница вашей книги (также известная как «корневая страница»). Это целевая страница для HTML-кода вашей книги. Все пути к главам/разделам будут относиться к этому корневому документу.

Список записей, каждая из которых соответствует главам вашей книги.

Путь к файлу, содержащему содержимое главы/раздела. Эти пути _относительны корневому документу.

Использовать подразделы глав¶

При желании вы можете разделить главу на несколько файлов (каждый из которых составляет раздел главы). Для этого используйте разделы: конфигурация, например:

Вот краткое описание разделов:

Список записей, определяющих подразделы главы. Это полезно, если вы хотите разделить главу на несколько страниц. Дополнительные сведения см. в разделе Как заголовки и разделы сопоставляются со структурой книги.

Используйте части для организации глав¶

При желании вы можете организовать главы по частям, используя ключ parts: следующим образом:

Вот краткое объяснение частей:

Список записей, каждая из которых определяет главу. Это полезно, если вы хотите использовать разные группы глав.

Структура статьи¶

Вы можете создать статью (например, одну страницу), а не целую книгу. Вы можете создать вывод для статьи из одного исходного файла или разделить его на несколько файлов (аналогично структуре книги).

В этом разделе содержится дополнительная информация о том, как это сделать.

Выполняется

Функция создания статей для Jupyter Book все еще находится в стадии проектирования и разработки. Эта функция может меняться со временем! Если у вас есть идеи, предложения или вы хотите помочь, см. руководство по внесению вклада .

Создать статью из одного файла¶

Вы можете создать отдельный HTML-файл для одной страницы Jupyter Book с помощью команды jupyter-book и указать для него отдельный файл, а не каталог книги:

Это создаст файл как обычно и поместит его в выходную папку с именем _build/_page/html/ .

Если файл находится в подкаталоге относительно папки _build, HTML-код будет находиться в папке _build/_page/html/.

Ваша страница будет называться mypage.html . Это будет работать для любого исходного файла контента, поддерживаемого Jupyter Book.

Создать статью из нескольких файлов¶

Вы также можете разделить статью на несколько входных файлов (например, если хотите хранить разделы отдельно). Для этого используйте параметр format: jb-article в файле _toc.yml.

Основное отличие состоит в том, что в формате jb-book используются части: и главы: синтаксис, а в формате jb-article используются только разделы: синтаксис.

Чтобы создать одну HTML-страницу из этих файлов (а не одну страницу на файл), используйте конструктор singlehtml.

Типы контента¶

Существует несколько типов записей, которые вы можете указать для указания на определенные типы контента. Вот краткий обзор:

Путь, указывающий на локальный текстовый файл, определяющий содержимое этой записи (глава, раздел или подраздел). Эти пути должны относиться к вашему файлу _toc.yml.

Шаблон в виде шара, который можно использовать для сопоставления с несколькими локальными файлами. Каждый из этих файлов будет собран и вставлен в ваш контент в том порядке, в котором glob их обнаружит.

Когда предоставляется заголовок: вместо полного URL-адреса используется его текст.

Вот пример, показывающий все три типа:

Создать оглавление из файлов содержимого¶

Вы можете использовать jupyter-book для создания файла оглавления из вашей книги, используя имена файлов содержания вашей книги. Для этого выполните следующую команду

При создании ссылок, хотя вы можете использовать стандартный HTML или Markdown, этот подход обычно подвержен множеству ошибок и неработающих ссылок.Существует генератор URL-адресов, который облегчит создание ссылок на другие страницы таким образом, чтобы ссылки не прерывались.

Стратегии ссылок

Одной из наиболее сложных частей сайта документации является поддержание точности и правильности всех внутренних ссылок. Когда вы используете единый источник, у вас обычно есть несколько выходных документов, которые включают определенные страницы для определенной аудитории. Потерянные ссылки – распространенная проблема, которую следует избегать.

Несмотря на то, что существует множество способов создания ссылок, я опишу лишь те, которые, по моему мнению, работают хорошо.

Создать внешнюю ссылку

При ссылке на внешний сайт используйте форматирование Markdown:

Если вам нужно использовать HTML, используйте обычный синтаксис:

Ссылки на внутренние страницы

При ссылке на внутренние страницы можно использовать тот же синтаксис:

Но что произойдет, если вы измените название страницы или ссылку? Jekyll не извлекает заголовок страницы автоматически при создании ссылок.

По моему опыту, такое кодирование ссылок приводит к большому количеству неработающих ссылок.

Управляемые ссылки

Я обнаружил, что для внутренних ссылок лучше всего хранить ссылку в файле YAML, полученном из оглавления.

В теме есть файл urls_mydoc.txt. Этот файл содержит тот же код, что и оглавление (но без условных квалификаторов). Он перебирает каждую страницу, указанную на боковой панели оглавления (а также в верхних меню навигации), и создает вывод, который выглядит следующим образом для каждой ссылки:

В выходной папке сайта (в ../doc_outputs) откройте urls_mydoc.txt и убедитесь, что он правильно заполнен (пробелы между записями не имеют значения). Затем вручную скопируйте содержимое файла mydoc_urls.txt и вставьте его в файл _data/mydoc/mydoc_urls.yml в папке вашего проекта.

Поскольку файл urls.txt создается из оглавления, вы можете быть уверены, что во встроенных ссылках будут использоваться те же заголовки и URL-адреса, что и в оглавлении и верхней части навигации.

Чтобы создать ссылку в теме, просто укажите соответствующее значение в файле urls.yml, например:

Это добавит в вашу тему следующее:

Вам не нужно беспокоиться о том, можно ли использовать синтаксис Markdown при вставке ссылки таким образом, потому что вставка осуществляется в формате HTML.

Чтобы вставить ссылку в контексте фразы, вы можете использовать следующий синтаксис:

При этом используется синтаксис Markdown. Если вы находитесь в файле или разделе HTML, используйте это:

Обратите внимание, что значение url обращается к URL-адресу только страницы, тогда как link получает заголовок и URL-адрес в формате ссылки.

Не следует слишком часто копировать содержимое файла urls.txt в источник данных YAML — только при создании новых страниц.

Используя этот подход, вы с меньшей вероятностью столкнетесь с неработающими ссылками.

Всегда проверяйте правильность содержания страницы

Вы должны обращаться с файлом sidebar_doc.yml с большой осторожностью. Каждый раз, когда вы добавляете страницу на свой сайт, убедитесь, что она указана в вашем файле sidebar_doc.yml (или в верхней части навигации). Если у вас нет страниц, перечисленных в вашем файле sidebar_doc.yml, они не будут включены в файл urls_mydoc.txt, и по мере роста вашего сайта будет сложнее распознавать страницы, отсутствующие в оглавлении.

Поскольку все страницы хранятся в корневом каталоге, список файлов может стать очень длинным. Обычно я нахожу страницы, переходя к странице на сервере предварительного просмотра, копируя имя страницы (например, mydoc_hyperlinks) и затем нажимая Shift + Shift в WebStorm, чтобы найти страницу.

Это единственный разумный способ найти ваши страницы, когда у вас сотни страниц в корневом каталоге. Если страница не указана в вашем оглавлении, вам будет сложно перейти к ней и найти ее.

Проверка неработающих ссылок

Еще один способ убедиться, что в выходных данных нет неработающих ссылок, — это создать PDF-файл. При создании PDF-файла обратите внимание на следующие две проблемы в выходных данных:

Оба случая указывают на неработающую ссылку. «Страница 0» означает, что Prince XML не смог найти страницу, на которую указывает ссылка, и поэтому не может создать перекрестную ссылку. Это может быть связано с тем, что страница не существует или якорь указывает на отсутствующее место.

Если вы видите «см. .» это означает, что ссылка (например, > на самом деле ни к чему не относится. В результате в выводе она просто пуста.

Примечание: чтобы Prince XML не пытался вставить перекрестную ссылку в ссылку, добавьте к ссылке class="noCrossRef".

Относительные пути ссылок

Сайт закодирован относительными ссылками. Там нет постоянных ссылок, URL-адресов или базовых URL-адресов. Структура папок, которую вы видите в каталоге проекта, — это тот же каталог папок, который создается в выходных данных сайта.

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

Например, чтобы создать ссылку на файл, хранящийся в файле files/doc/whitepaper.pdf, используйте в качестве ссылки «files/doc/whitepaper.pdf».

Почему бы не помещать страницы во вложенные папки? Если вы поместите страницу во вложенную папку, то ссылки на таблицы стилей, JavaScript и другие источники не будут работать. На страницах этих подпапок вам нужно будет использовать ../, чтобы перейти на уровень выше в каталоге, чтобы получить доступ к таблицам стилей, JavaScript и т. д. Но если у вас есть некоторые страницы в папках на одном уровне, другие в под-под -folders и другие в корне, пытаясь угадать, какие файлы должны содержать ../ или ../../ или вообще ничего, а какие не должны быть кошмаром.

Jekyll обходит некоторые из этих вариаций пути ссылки, используя baseurl и добавляя код, который добавляет baseurl перед ссылкой. Это преобразует ссылки в абсолютные, а не в относительные.

С абсолютными ссылками сайт отображается только по настроенному вами базовому URL. Это проблематично для технической документации, потому что вам обычно нужно перемещать файлы из одной папки в другую в зависимости от версий, которые вы архивируете, или когда вы перемещаете свою документацию из черновика в тестовую в рабочие папки.

Ограничения со ссылками

Одним из недостатков этой темы является то, что заголовки ссылок на боковой панели и встроенных ссылок не обязательно должны совпадать с заголовками, указанными на каждой странице. Вы должны вручную синхронизировать заголовки страниц с заголовками, перечисленными на боковой панели и в верхней части навигации. Хотя потенциально я мог бы избавиться от ключа заголовков в теме статьи, это затруднило бы определение того, какую страницу вы редактируете.

Последнее обновление страницы: 30 ноября 2015 г.
Создание последнего сайта: 14 апреля 2018 г.

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

Проблема

В этой статье предположим, что мы разрабатываем платежный сервис, который подключается к внешнему платежному провайдеру. Значения торгового счета не совпадают в рабочей среде и среде разработки. Это означает, что каждый раз, когда мы переключаем среды, мы должны изменять значения и перекомпилировать код, что не очень хорошо.

Решение

Лучшее решение нашей проблемы — передать данные конфигурации нашего приложения во внешний мир. Таким образом, нам не нужно перекомпилировать наш код каждый раз, когда мы переключаемся между средами. Мы сможем переопределить значения параметров конфигурации с меньшими усилиями. Наше приложение Spring сможет считывать значения учетной записи продавца из внешних источников, таких как переменные среды, аргументы командной строки и файлы свойств.

Экстернализация данных конфигурации

Источники ресурсов

Существуют различные способы экстернализации данных конфигурации приложения Spring. Мы можем использовать переменные среды, файлы свойств (например, в формате YAML или с расширением файла .properties) и аргументы командной строки для указания свойств нашего приложения. Мы также можем хранить файлы свойств в произвольных местах, а затем сообщать нашему приложению Spring, где их искать.

Файлы свойств

По умолчанию приложение Spring загружает свойства из application.properties или application.yml из следующих местоположений, перечисленных ниже в порядке приоритета (т. е. файл свойств в расположениях выше в списке переопределяет те, которые определены в более низких местах) и добавляет их в окружающая среда:

подкаталог config текущего каталога
текущий каталог
пакет конфигурации в пути к классам
в корне пути к классам

Имя файла конфигурации по умолчанию — application . Мы можем указать другое имя, если захотим, используя ключ свойства среды spring.config.name . См. пример ниже: мы заменили имя конфигурации Spring по умолчанию на new_name .

Пользовательское местоположение

Мы можем внедрить свойство приложения или файлы YAML, используя свойство среды spring.config.location . Мы можем установить его значение так, чтобы оно указывало на пользовательские местоположения, которые могут быть где угодно, и тем самым мы переопределим местоположения по умолчанию. См. пример ниже:

Примечание. Когда мы хотим указать местоположение каталога, мы должны убедиться, что значение spring.config.location заканчивается на / (например, spring.config.location=classpath:/config/ ) и что файл конфигурации имя по умолчанию. Также можно указать дополнительные местоположения для поиска перед местоположениями по умолчанию, используя ключ свойства spring.config.additional-location .

Spring Boot также поддерживает расположения с подстановочными знаками, и эта функция становится полезной в средах, где есть несколько источников свойств конфигурации, например в средах Kubernetes. Например, если у вас есть некоторая конфигурация Redis и некоторая конфигурация MySQL, вы можете захотеть разделить эти две части конфигурации, требуя, чтобы обе они присутствовали в application.properties, к которым может привязываться приложение. Это может привести к тому, что два отдельных файла application.properties будут смонтированы в разных местах, таких как /config/redis/application.properties и /config/mysql/application.properties. В таком случае расположение подстановочного знака config/*/ приведет к обработке обоих файлов.

Форматы файлов

Файл свойств приложения может быть в формате YAML или иметь расширение .properties . Если мы поместим эти два файла свойств в одну и ту же папку конфигурации, файл application.properties будет иметь приоритет над файлом application.yml. В следующем фрагменте кода показаны настройки учетной записи продавца, определенные в каждом типе файла свойств.

application.properties

application.yml

Файл YAML и файл .properties

YAML – это удобный для человека стандарт сериализации данных, который обычно используется в файлах конфигурации. Это расширенный набор JSON, который очень удобен при указании иерархических данных конфигурации. Мы предпочитаем файлы YAML, потому что они более четкие и удобочитаемые, особенно по сравнению с файлом .properties, и помимо его удобочитаемости, у него есть другие очень полезные функции, такие как безопасность типов и т. д.

Для загрузки файла YAML нашему приложению Spring требуется библиотека SnakeYAML в пути к классам. В приведенном примере кода мы использовали стартеры Spring Boot, поэтому нет необходимости включать библиотеку в путь к классам.

Несколько профилей

YAML позволяет нам указать несколько профилей в одном файле конфигурации, тогда как с файлом .property нам может потребоваться предоставить файл конфигурации для каждого профиля. Давайте посмотрим на пример ниже.

а) файл YAML:

application.yml

b) файл .properties:

В случае файла .properties, если мы хотим определить два профиля, нам нужно создать отдельный файл конфигурации для каждого профиля. В имени каждого файла конфигурации должно быть достаточно -.properties . См. приведенный ниже пример профилей наших приложений для разработки и производства.

application-development.properties

application-production.properties

Нам может понадобиться application.properties по умолчанию, если есть свойства, общие для профилей разработки и производства.

application.properties

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

Подробнее о профилях можно прочитать в этом сообщении Spring Profile.

Читаемость

YAML поддерживает списки и карты в качестве иерархических свойств, и по сравнению с файлом .properties версия YAML более удобочитаема. Представьте, что мы хотим настроить параметры соединения для реальной и тестовой сред. Сначала мы зададим имена соединений в виде списка, а затем сопоставим имя соединения с соответствующим URL-адресом с помощью карты, как показано ниже. Давайте посмотрим, как YAML упрощает эту настройку по сравнению с файлом .properties.

application.yml

application.properties

Мы предоставили тестовые примеры проверки сопоставлений в тестовых пакетах примера кода этой статьи.

Аргументы командной строки

Когда мы передаем аргумент командной строки, приложение Spring преобразует его в свойство и добавляет в среду Spring. Мы можем использовать эти аргументы командной строки для настройки параметров нашего приложения, например, следующие аргументы командной строки переопределяют порт сервера приложений, определенный в любом другом источнике свойств. Если мы запускаем наше приложение с помощью команды maven или команды java, мы все равно получим тот же результат.

Используя команду maven:

Команда JVM:

Также можно передавать несколько аргументов одновременно. Используя приведенный выше пример, мы передадим еще одно свойство, порт сервера, как показано ниже.

Команда Maven (через пробел):

Использование команды JVM:

Переменные среды

Учитывая, что мы не можем изменять значения наших свойств через командную строку, мы можем воспользоваться преимуществами переменных среды. Приложение Spring может считывать переменные среды, и при запуске приложение Spring ищет переменную среды с именем SPRING_APPLICATION_JSON, которая может содержать набор свойств с использованием встроенного JSON.Мы можем поэкспериментировать, переопределив адреса подключения, определенные в нашем файле свойств, выполнив следующие действия.

Давайте откроем наш терминал и выполним следующую команду. Команда устанавливает переменные среды нашего приложения, переопределяя параметры подключения.

Затем запустим наше приложение

Когда мы проверяем наш журнал, мы замечаем, что адреса подключения в профиле разработки были переопределены, а значения в файле JSON, которые мы передали через переменную среды, имели приоритет.

Внедрение свойства

Существуют различные способы добавления значений свойств в наше приложение из источников свойств. Мы можем использовать аннотацию @Value, абстракцию Spring Environment или привязать эти значения к структурированному объекту, аннотированному с помощью @ConfigurationProperties .

@Значение

Мы можем использовать этот метод, если у нас есть несколько свойств, но не рекомендуется, если у нас много свойств. Представим, что если в мерчант-аккаунте было более двадцати свойств, то это значит, что мы собирались указать аннотацию @Value двадцать раз. Фрагмент кода ниже показывает, как мы можем использовать эту аннотацию для добавления значения свойства в наше приложение.

Важно убедиться, что имя свойства @Value совпадает с именем, указанным в источниках свойства.

@ConfigurationProperties

Если у нас есть несколько свойств, мы можем сгруппировать их вместе и сопоставить с классом POJO. Это предоставит нам структурированный и типобезопасный объект, который мы можем внедрить в любом месте нашего приложения. Таким образом, вместо использования аннотации @Value значения свойств можно получить с помощью методов получения этого POJO.

Класс POJO должен быть снабжен аннотациями @ConfigurationProperties и @Component, как указано выше. Значение префикса, указанное в аннотации, должно совпадать с префиксом свойства, определенным в файле application.yml, как указано выше.

application.yml

Важно отметить, что мы также можем использовать аннотацию @ConfigurationProperties для сопоставления списков и карт, как показано ниже:

Порядок приоритета данных конфигурации

В приложении Spring Boot может быть несколько источников свойств. Поэтому важно знать источник свойства, который будет иметь приоритет над другими. Например, если мы предоставили конфигурацию для нашего приложения, используя файл application.yml, и во время выполнения приложения мы решили передать аргументы командной строки, тогда значения свойств в файле application.yml будут переопределены значениями, указанными в аргументах командной строки. .

Приведенный ниже порядок источников свойств используется Spring Boot 2.2.x. Источник свойств, расположенный выше в списке, имеет приоритет над источниками, расположенными ниже него.

Свойства глобальных настроек в папке $HOME/.config/spring-boot, когда devtools активен
Аннотации @TestPropertySource к вашим тестам.
Свойства в ваших тестах. Доступно в @SpringBootTest и в тестовых аннотациях для тестирования определенного фрагмента вашего приложения.
Аргументы командной строки
Свойства из SPRING_APPLICATION_JSON (встроенный JSON, встроенный в переменную среды или системное свойство)
Параметры инициализации ServletConfig
Параметры инициализации ServletContext
Атрибуты JNDI из java:comp/env .
Свойства системы Java, например System.getProperties()
Переменные среды ОС.
RandomValuePropertySource со свойствами только в случайном порядке.* .
Специфичные для профиля свойства приложения за пределами упакованного jar-файла (варианты application-.properties и YAML)
Специфические для профиля свойства приложения, упакованные внутри jar-файла (варианты application-.properties и YAML)
Свойства приложения за пределами упакованного файла jar (варианты application.properties и YAML)
Свойства приложения, упакованные внутри jar-файла (варианты application.properties и YAML)
Аннотации @PropertySource к вашим классам @Configuration. Обратите внимание, что такие источники свойств не добавляются в среду до тех пор, пока не будет обновлен контекст приложения. Слишком поздно настраивать определенные свойства, такие как logging.* и spring.main.*, которые считываются до начала обновления
Свойства по умолчанию (задаются параметром SpringApplication.setDefaultProperties )

Заключение

Рекомендуется экстернализовать наши данные конфигурации, и если есть много свойств конфигурации, мы можем сгруппировать их в простой класс Java и использовать аннотацию @ConfigurationProperties, чтобы структурировать нашу конфигурацию и сделать ее безопасной для типов. Однако самая большая проблема с внешней конфигурацией заключается в обеспечении того, чтобы развернутое приложение работало с правильной конфигурацией.Поэтому важно соблюдать осторожность при настройке приложения, которое использует разные источники свойств для разных сред. Пример кода для этой статьи можно найти здесь, на GitHub.

Итак, я был в восторге от функций 3.x, Twig и всего остального, но переход на файлы YML ломает мою любимую часть рабочего процесса уценки:

с более сложным синтаксисом (с отступом во всех строках содержимого уценки на два пробела) автономные редакторы уценки (Mou, Byword, Marked и т. д.) не понимают его правильно, а встроенный предварительный просмотр в этих приложениях не работать больше.

Поэтому мой вопрос заключается в том, есть ли (и как) вероятность того, что:

мы можем убрать это требование об отступе в 2 пробела или
мы можем просто ссылаться на файлы уценки .md из файла .yml, что позволяет писать контент в родном формате уценки

Текст был успешно обновлен, но возникли следующие ошибки:

kvakes прокомментировал 16 апреля 2012 г.

С другой стороны, это собственный формат YAML для вставки больших фрагментов текста, поэтому должно быть лучшее решение проблемы.

прокомментировал lunelson 16 апреля 2012 г.

Да, я полагал, что первый вариант может быть невозможен, поскольку он обменивает нарушение правил одного формата на другой;

поэтому я задался вопросом, нельзя ли связать файл, поместив что-то вроде следующего в файл page.yml:

… что также позволило бы вам иметь практически любое имя для файла содержимого (при условии, что соответствующий бит существует в файле YML), и это может быть даже более семантическим: поскольку файл YAML (названный соответствующим образом с его шаблоном) представляет собой просто набор пар "ключ-значение" и ссылок, а текстовые и медиафайлы контента являются отдельными, с именами в соответствии с их собственным контекстом.

kvakes прокомментировал 16 апреля 2012 г.

Поскольку в папке есть только один файл .yml, мы также можем просто добавить в эту папку content.md, чтобы инициализировать переменную содержимого, которая будет содержать Markdown. Кроме того, мы могли бы добавить что-то вроде text.html с HTML-содержимым и т. д. Согласие по поводу конфигурации, знаете ли.

прокомментировал lunelson 16 апреля 2012 г.

да, это может сработать, хотя не каждый тип страницы будет содержать блок контента, называемый "контент", и не обязательно будет содержать только один блок.

Я считаю, что ключевым файлом для любой страницы является файл .yml, и что текстовое (т.е. не мультимедийное) содержимое либо записывается в этот файл (например, заголовок: Моя страница ), либо может быть при необходимости связан с дополнительным файлом:

Примечание: приведенный выше синтаксис, скорее всего, неверен

kvakes прокомментировал 16 апреля 2012 г.

вы получите контекст, содержащий все переменные из pagename.yml плюс переменные page.content , page.long_text , page.another, заполненные тем, что вы поместили в соответствующие файлы; и (возможно!) page.something с содержимым HTML.

прокомментировал lunelson 16 апреля 2012 г.

Ах да, я только что понял, что вы имели в виду раньше.

Действительно, это может быть самым простым для пользователя, если синтаксический анализатор просто ищет что-либо с расширением .md или .html и добавляет его к значениям для этой страницы (ключи равны имени файла). Подобно тому, как он собирает медиа-информацию. И любые другие пары ключ-значение входят в файл YAML, и имя шаблона по-прежнему соответствует тому, как называется файл YAML. Это было бы очень мощно.

Кто-нибудь из участников разработки хочет высказаться по этому поводу?

комментарий kolber от 17 апреля 2012 г.

Это действительно интересно.
Отступ с двойным пробелом меня раздражал и в новой версии.

Мне нравится эволюция идеи, которую предлагает @kvakes. Поскольку YAML не имеет внешнего механизма загрузки файлов, его необходимо было бы добавить, что несколько нарушило бы соглашение.

Но идея использовать имя файла в качестве ключа имеет большой смысл. В принципе, это довольно элегантное решение.

kvakes прокомментировал 17 апреля 2012 г.

Включение файлов уценки в качестве переменных не имеет никакого отношения к YAML, это просто еще один способ инициализировать переменную в контексте шаблона, поэтому мы не нарушаем никаких соглашений. И пользователи смогут решить, определять ли длинные фрагменты текста через YAML или через внешние файлы.

Одна проблема, которую я вижу, заключается в том, что в более ранней версии Stacey у нас могли быть, например, $коллекции файлов .html. Или коллекции любых файлов, отличных от .txt. И наша новая функция несколько противоречит тому, что было раньше.

комментарий kolber от 17 апреля 2012 г.

О, с комментарием "YAML не имеет внешнего механизма загрузки файлов" я имел в виду идею разрешить
content-block-1: >content-1.md
Это означало бы расширение синтаксического анализатора YAML, чего я бы предпочел избежать. Ваше альтернативное решение, включающее файлы .md в качестве переменных страницы — отличный способ обойти эту проблему.

На самом деле я не думаю, что это вызовет какие-либо конфликты с коллекциями $html. Я думаю, что эти двое могли бы сидеть рядом, не вызывая проблем.

прокомментировал lunelson 17 апреля 2012 г.

Я вижу, что @kvakes имеет в виду с потенциальным конфликтом с $collections ; хотя может это не совсем прямой конфликт?

В любом случае это наводит меня на две мысли:

Возможно, можно было бы разрешить регистрировать все файлы, кроме файла .yml в папке (возможно, также за исключением именованных коллекций, таких как _thumbnails ), как значения с именем файла в качестве ключа, и в то же время разрешить их сбор в массивы $коллекции тоже по-старому?; или поочередно
Может быть, есть способ обращаться непосредственно к файлу, а не зацикливаться на коллекциях?

что предполагает, что возможно следующее

и т. д. Я основываюсь на том, что читаю в документации по версиям 2.3.x и 3.x

прокомментировал lunelson 17 апреля 2012 г.

По дороге домой я еще подумал об этом и хотел бы предложить еще одно наблюдение:

Функция $collection имеет смысл для типов данных, которые доступны для чтения извне и будут передаваться непосредственно в вывод html с помощью инструкций шаблона. Логично предположить, что при их анализе система собирает больше, чем просто @content этих файлов, она также собирает @name , @file_name , @url и т. д.

Но уникальность использования файлов .yml и .md (и, если уж на то пошло, .txt ) заключается в том, что они анализируются только внутри, а не вставляются непосредственно в вывод HTML, и единственная релевантная информация, полученная из них, @file_name и @content (мы можем предположить, что это текст UTF-8).

Может быть, идея анализа значения страницы непосредственно из файлов с вводом имени файла должна быть ограничена этими типами?

Я по-прежнему думаю, что синтаксис для обращения к файлу по имени был бы замечательным (см. мой предыдущий комментарий), но я думаю, что это еще один запрос на добавление функции.

В любом случае, я очень рад, что эта функция может увидеть свет… удачи

прокомментировал lunelson 12 мая 2012 г.

Хм. Нет интереса к этому вопросу со стороны активных разработчиков? Может быть, нам стоит изменить название ;)

прокомментировал kolber 14 мая 2012 г.

Мне нравится эта идея, но у меня еще не было возможности ее рассмотреть.

прокомментировал lunelson 14 мая 2012 г.

Круто. Рад это знать

Прокомментировал StephenLovell 14 июля 2012 г.

Подводя итог, можно сказать, что большинство моих проблем беспокоят и других, но я не сторонник включения файла .md в файл .yml в качестве единственного решения.

Меня беспокоит (и поправьте меня, если я неправильно понял) то, что при таком подходе ваш заголовок, дата и т. д. находятся в вашем файле .yml, а ваш контент — в вашем файле .md. Это напрасная разлука. Я думаю, что действительно должен быть двухсторонний подход к этому.

Разрешите включение файлов .md, как сказано выше. Это отлично работает, если у вас много контента страницы, который вы хотите разделить на более управляемые фрагменты .md.
Разрешить включение своего рода оболочки .md в сам файл .yml, которая будет анализировать все в «тегах» оболочки так же, как включенный файл .md. Таким образом, если ваш контент состоит из одного абзаца, но должен быть в формате .md И вам нужно избежать надоедливых отступов, вам не нужно создавать еще один файл, только для одного абзаца.

Итак, вы получите что-то вроде этого (извините за грубый синтаксис):

Если синтаксический анализатор собирает ключ, оканчивающийся на '(md)', он ищет путь к файлу в значении, если вместо этого найден канал, то он обрабатывает следующий блок как .md без обязательного отступа.

Что касается контекста контента, я также считаю особенно полезным иметь дату, заголовок и т. д. в том же файле, что и контент. Принудительное разделение затрудняет просмотр всего вашего контента.

Я понимаю, что в соответствии с соглашением YAML, но это одна из областей, где YAML с треском терпит неудачу из-за отсутствия обработки литералов блока без отступа, поэтому здесь стоит рассмотреть небольшую «модификацию», чтобы помочь сохранить более честный пользовательский ввод - > вывод.

kolber прокомментировал 19 июля 2012 г.

Полностью согласен с этими опасениями, и это то, что вызывает у меня проблемы.
Я экспериментировал с различными решениями в некоторых моих собственных проектах, в том числе с внешним файлом .md.

Я склонен думать, что ограждение контента с уценкой является лучшим подходом, так как при этом весь ваш контент хранится в одном файле. Что значительно упрощает управление.

Это синтаксис, с которым я играл:

Где +++ могут располагаться на отдельных строках или содержать более трех +:

f0x2501 прокомментировал 19 июля 2012 г.

Колбер,
Ваше решение рок.
Я также считаю важным хранить все содержимое страницы в одном файле.

Есть также суффиксный способ

o-l-e прокомментировал 19 июля 2012 г.

Привет, мне нравятся оба последних предложения.

@mentat-fr, как бы вы закрыли тег, или это произойдет автоматически при записи новой переменной ниже этого?
Извините, я не знаком с yml.

Это может быть глупым предложением (с точки зрения пользователя), но если вы можете использовать суффикс, чтобы контролировать, использовать уценку или нет, то не могли бы вы также использовать, например, точку с запятой или другой символ?

kvakes прокомментировал 19 июля 2012 г.

синтаксис переменной content(.md|(md)|_md)
файлы типа content.md (без явного указания пути)

Поскольку Стейси использует очень небольшое подмножество Yaml (?), мы можем просто запретить Стейси использовать Yaml, например. откат к старому варианту Stacey, где, если переменная начинается с \n, она обрабатывается как Markdown.

Если мы хотим придерживаться Yaml, я бы не стал менять синтаксис, просто неправильно менять что-то, что поддерживается другими, мы больше не сможем сказать, что это Yaml, потому что 1) пользователи будут сбиты с толку , потому что наш Yaml отличается, 2) "неправильный" синтаксис может иметь другие зависимости в Yaml, или просто философия, которую мы не понимаем. Мы также можем достать об этом Кларка Эванса. Но если нам нужна сложность Yaml, я бы придерживался файлов *.md, рассматриваемых как переменные. Я понимаю, что это не идеальное решение.

Прокомментировал StephenLovell 19 июля 2012 г.

на данный момент мне больше всего нравится

У меня есть желание следовать синтаксису yaml, но я бы в любой день пожертвовал этим стандартом ради UX.

Это изменяет правила, опускает требование отступа и символ вертикальной черты. Однако ваш ключ по-прежнему является ключом, и вы можете легко выполнить синтаксический анализ уценки, отсканировав все ключи с .md в конце.

Включение внешних файлов — полезная опция, но она не должна использоваться по умолчанию.

kolber прокомментировал 19 июля 2012 г.

К сожалению, нам нужно указать как начало, так и конец содержимого уценки для синтаксического анализа, в противном случае перечисленные выше решения были бы отличными.

Основная проблема заключается в том, что нам необходимо предварительно проанализировать текстовый файл и преобразовать блоки уценки в текстовые блоки, совместимые с YAML, прежде чем передавать их обратно парсеру YAML.

Если у вас, ребята, не было альтернативных идей о том, как мы могли бы реализовать вышеизложенное?

Прокомментировал StephenLovell 19 июля 2012 г.

Простите меня за невежество, но я полагаю, что предполагал, что двоеточие указывает на начало ЗНАЧЕНИЯ, а новая строка плюс следующее ЗНАЧЕНИЕ или EOF указывают на окончание ЗНАЧЕНИЯ. KEY с суффиксом .md указывает на то, что он должен обрабатываться как уценка.

content: обычный KEY

content.md: это KEY, помеченный для синтаксического анализа уценки.

Короче говоря,
любой KEY с суффиксом .md преобразуется в литерал блока yaml и передается в yaml для анализа. И все ЗНАЧЕНИЯ начинаются с ДВОРЕЦА и заканчиваются НОВОЙ СТРОЧКОЙ + СЛЕДУЮЩИЙ КЛЮЧ или EOF.

Мне кажется, что это упускает необходимость явно помечать начало и конец с помощью +++, да, препроцессор должен делать немного более тяжелую работу, но мне кажется возможным включить вышеизложенное, чтобы указать запуск и остановка VALUE.

Или я что-то упустил?

прокомментировал kolber 20 июля 2012 г.

Это немного сложнее.

Возьмите следующий пример:

Нам очень сложно определить с абсолютной уверенностью, где заканчивается текстовый блок и начинается новый ключ.
Вот почему YAML использует отступы, чтобы отличать текстовые блоки от ключей.

jaywilliams прокомментировал 20 июля 2012 г.

прокомментировал kolber 20 июля 2012 г.

У меня есть, и мне очень нравится такой подход, тем более, что в наши дни он довольно распространен.

Проблема в том, что я часто использую несколько блоков контента уценки, которые можно обрабатывать с помощью нескольких разделов YAML, но вы теряете возможность называть переменные.

Это означает, что в конечном итоге вы столкнетесь с формой автоматического именования переменных, например content1 , content2 и т. д., что кажется немного неуклюжим.

f0x2501 прокомментировал 20 июля 2012 г.

@o-l-e правильно, поэтому, если вам нужно закрытие/окончание, почему бы не использовать определенный тег, например

@kolber: каким бы ни было решение, всегда используйте стандартный синтаксис идентификации yml.

o-l-e прокомментировал 20 июля 2012 г.

@mentat-fr и @kolber:
У меня возникло ощущение, что вам нужно закрыть переменную, содержащую уценку, после ее открытия.

С точки зрения пользователей, мне нравится возможность иметь столько блоков уценки, сколько я хочу, и их переменные с именами, которые я хочу. Это одна из вещей, которая очень привлекает Стейси. И таким ясным простым языком.

Я предполагаю, что окончательное решение должно быть принято (например):

для кого Стейси? (разработчик или "визуальный" тип)
что для визуального типа/пользователя кажется "легким" и в духе Стейси? (предыдущая версия)
Куда идет Стейси?(следующий уровень и более технический, или меньше шагов для публикации)
и т. д.

Лично как "визуальный" тип, я смотрел на другие, такие как Jekyll или подобные вещи, но либо они слишком сложны для установки (запуск сценариев оболочки и т. д.), либо они слишком разбиты на части (файлы здесь и там для любой маленькой строки текста).

Я знаю, что с точки зрения программиста повторное использование битов — это то, что нужно, но самое замечательное в stacey — это простота и доступность, которые он дает таким дизайнерам, как я, или другим людям, не занимающимся программированием. Люди, которым я предложил Стейси, просто в восторге. Dropbox как способ перетаскивания материалов в папки и простой характер уценки (которая очень быстро становится стандартом) в простых документах .txt.

Я думаю, что некоторые из новых функций ветки действительно хороши, и я вижу, что Стейси можно продвинуть намного дальше с точки зрения разработчиков. Но, честно говоря, я даже не знал, что такое документ .yml, пока не прочитал об этом в этой группе обсуждения (не говоря уже о том, что когда-нибудь он может стать стандартом).

Я не хочу показаться оборонительным или непрогрессивным, но лично я просто надеюсь, что любое решение будет чем-то "человеческим", простым и быстрым.
Это то, что привлекло меня в Стейси в первую очередь :)

Читайте также: