быстрые страницы
vements to styling
Дополнительную информацию о том, почему мы прекратили поддержку этого проекта, можно найти здесь.
fastpagesПростая в использовании платформа для ведения блогов с поддержкой блокнотов Jupyter, документов Word и Markdown.
fastpages использует GitHub Actions для упрощения процесса создания сообщений в блоге Jekyll на страницах GitHub из различных входных форматов.
fastpages предоставляет следующие возможности:Более подробный список функций смотрите ниже.
Посмотреть демо-сайт
fastpagesfastpages предоставляет следующие возможности:Создайте копию этого репозитория, нажав на эту ссылку. Обязательно войдите в свою учетную запись, иначе вы увидите ошибку 404. Назовите свой репозиторий как угодно, кроме {your-username}.github.io.
GitHub Actions автоматически откроет PR в вашем новом репозитории примерно через 30 секунд после создания копии. Следуйте инструкциям в этом PR, чтобы продолжить.
Если вы не видите PR, убедитесь, что в вашей организации включены сторонние действия: Настройки -> Действия -> Разрешения на действия -> Включить локальные и сторонние действия для этого репозитория.
Подробное описание этапов настройки (с некоторыми дополнительными советами) смотрите в этом видеоуроке по настройке блога на fastpages от Абдула Маджеда.
Read and Write и установите флажок Allow GitHub Actions to create and approve pull requests . 
После предоставления разрешений перейдите на вкладку « Actions в верхней части домашней страницы вашего репозитория, где вам будет представлен список выполненных действий. Сначала нажмите на неудачный запуск (пункт с красным крестиком):
Вы попадете на экран, где в правом верхнем углу будет кнопка, позволяющая повторно запускать задания.
После этого должен появиться запрос на включение.
_posts , _notebooks или _word . Вы можете просмотреть примеры контента в этих папках в этом репозитории, чтобы узнать, как структурировать контент. Самое важное, на что следует обратить внимание, — это начальная часть, которая более подробно обсуждается ниже. Кроме того, вы можете добавить дополнительные страницы, которые будут отображаться на панели навигации вашего блога в каталоге _pages . Обратите внимание, что содержимое каталога _word не поддерживает вступительную часть. Front Matter позволяет включать и выключать различные параметры для каждого сообщения в блоге, а также передавать метаданные различным функциям fastpages.
В записной книжке вступительная часть определяется как ячейка уценки в начале записной книжки со следующим содержимым:
# "Title"
> "Awesome summary"
- toc: false
- branch: master
- badges: true
- comments: true
- categories: [ fastpages, jupyter ]
- image: images/some_folder/your_image.png
- hide: false
- search_exclude: true
- metadata_key1: metadata_value1
- metadata_key2: metadata_value2Аналогично, в документе с уценкой та же самая вступительная часть будет определена следующим образом в начале документа:
---
title : " My Title "
description : " Awesome description "
layout : post
toc : false
comments : true
image : images/some_folder/your_image.png
hide : false
search_exclude : true
categories : [fastpages, jupyter]
metadata_key1 : metadata_value1
metadata_key2 : metadata_value2
---Дополнительные метаданные не являются обязательными и позволяют настроить пользовательскую вступительную часть.
Обратите внимание: все, что определено в начале, должно быть допустимым YAML. Непредоставление действительного YAML может привести к тому, что ваша страница не будет отображаться в вашем блоге. Например, если вы хотите, чтобы в вашем заголовке было двоеточие, вы должны экранировать его двойными кавычками, например:
- title: "Deep learning: A tutorial"
Дополнительную информацию см. в этом руководстве по YAML.
Title желаемым заголовком, а Awesome summary — желаемым резюме.Примечание. Рекомендуется заключать эти значения в двойные кавычки, чтобы избежать двоеточий и других символов, которые могут нарушить работу анализатора YAML.
fast_template автоматически сгенерирует для вас оглавление на основе заголовков уценки! Вы можете включить или выключить эту функцию, установив для toc: значение true или false .Этот вариант работает только для ноутбуков.
branch используется для дополнительного отображения ссылки вашего блокнота на Colab и GitHub в сообщении блога. По умолчанию будет использоваться master , если вы не укажете его в записной книжке.badges значение false . По умолчанию это truebadges: true , все четыре значка (GitHub, Binder, Deepnote, Colab) будут отображаться по умолчанию. Вы можете настроить эти значения по умолчанию с помощью параметра default_badges в параметрах конфигурации всего сайта. Если вы хотите скрыть значок только в отдельном сообщении, вы можете установить в начале hide_{github,colab,binder,deepnote}_badge: true . Например, если вы хотите скрыть значок Binder для отдельной записной книжки, но хотите, чтобы другие значки отображались, вы можете установить это во вступительной части:
- badges : true
- hide_binder_badge : truerequirements.txt с общими пакетами, которые вы используете для всех своих записных книжек, в корень вашего репозитория. Подробную информацию можно найти в официальной документации Binder.Вы можете разместить список категорий, разделенных запятыми, в квадратных скобках для публикации в блоге, что сделает публикацию видимой на странице тегов сайта вашего блога. Например:
В блокноте:
# "My Title"
- categories: [fastpages, jupyter]
В документе уценки:
---
title: "My Title"
categories: [fastpages, jupyter]
---
Предварительный просмотр того, как это выглядит, можно посмотреть здесь.
show_tags значение true или false в _config.yml : # Set this to true to display tags on each post
show_tags : true Комментирование сообщений в блогах осуществляется с помощью Utterances — способа реализации комментариев с открытым исходным кодом и без рекламы. Все комментарии хранятся в задачах репозитория вашего блога на GitHub. Вы можете включить это, установив для comments значение true . По умолчанию это значение false .
Чтобы включить комментарии с помощью высказываний, вам необходимо сделать следующее:
На сайтах социальных сетей, таких как Twitter, предварительный просмотр изображения может автоматически отображаться вместе с вашим URL-адресом. При указании image на лицевой стороне эти метаданные передаются сайтам социальных сетей для визуализации этого изображения. Вы можете установить это значение следующим образом:
- image: images/diagram.png
Примечание. Для этого параметра вы можете ссылаться только на файлы изображений и папки в папке /images вашего репозитория.
Возможно, вы захотите запретить размещение сообщения в блоге на главной странице, но при этом иметь общедоступный URL-адрес, который вы можете просмотреть или незаметно поделиться. Вы можете скрыть сообщение в блоге с домашней страницы, установив для параметра hide значение true . По умолчанию для этого параметра установлено значение false .
Рекомендуется использовать постоянные ссылки, чтобы создать предсказуемый URL-адрес для скрытых сообщений в блоге. Вы также можете установить для параметра search_exclude значение true если вы не хотите, чтобы пользователи находили ваше скрытое сообщение при поиске.
По умолчанию сообщения на вашей главной странице сортируются по дате. Однако вы можете захотеть, чтобы одна или несколько публикаций в блоге всегда появлялись в самом верху вашей домашней страницы. Другими словами, вы можете захотеть, чтобы определенные публикации были «закреплены» или «прикреплены». Для этого укажите заголовок sticky_rank в том порядке, в котором вы хотите, чтобы ваши прикрепленные сообщения появлялись. Сообщения блога, для которых не задан этот параметр, по умолчанию сортируются по дате после прикрепленных сообщений.
Например, рассмотрим эти три поста с уценкой (также работает для блокнотов).
2020-01-01-Post-One.md
---
title : Post One
sticky_rank : 1
--- 2020-02-01-Post-Two.md
---
title : Post Two
sticky_rank : 2
--- 2020-04-01-Post-Three.md
---
title : Post Three
--- Однако, поскольку указан sticky_rank , сообщения в блоге сначала будут отсортированы по Sticky_rank в порядке возрастания, а затем по дате в порядке убывания , поэтому порядок этих сообщений будет выглядеть следующим образом:
Без sticky_rank приведенные выше сообщения фактически будут отсортированы в обратном порядке из-за дат, связанных с каждым сообщением.
Примечание. Закрепление также работает для блокнотов:
# "My cool blog post"
> "Description of blog post"
- sticky_rank: 2
fastpages поставляется со встроенным поиском по ключевым словам на базе lunr.js. Вы можете запретить появление сообщения или страницы блога в результатах поиска, установив для параметра search_exclude значение false . По умолчанию для этого параметра установлено значение true .
Каждому рекомендуется персонализировать свой сайт блога, установив параметры конфигурации для всего сайта . Эти параметры можно найти в /_config.yml . Ниже приводится описание различных доступных опций.
title : это заголовок, который отображается в верхнем левом углу заголовка всех ваших страниц.
description : это описание будет отображаться в различных местах при создании предварительного просмотра вашего сайта (например, в социальных сетях).
github_username : это позволяет вашему сайту отображать ссылку на вашу страницу GitHub в нижнем колонтитуле.
github_repo : это позволяет вашему сайту отображать обратные ссылки на ваш репозиторий для различных функций, таких как ссылки на GitHub, Colab и Deepnote для блокнотов.
url : это не нужно менять, если у вас нет личного домена. Примечание. Оставьте в этом значении символ /.
baseurl : инструкции см. в комментариях в /_config.yml («Специальные инструкции для baseurl» по правильной установке этого значения. Если у вас нет личного домена, вы, вероятно, можете игнорировать эту опцию.
email : в настоящее время не используется. Игнорировать.
twitter_username : создает ссылку в нижнем колонтитуле на вашу страницу Twitter.
use_math : установите для этого параметра true , чтобы получить поддержку математических уравнений LaTeX. По умолчанию этот параметр отключен, так как в противном случае JavaScript загружается на каждую страницу, которая не может быть использована.
show_description : показывает описание под заголовком ваших сообщений в блоге на вашей домашней странице, содержащее список ваших сообщений в блоге. По умолчанию установлено значение true .
google_analytics : при желании можно использовать идентификатор Google Analytics для отслеживания.
show_image : если установлено значение true, используется параметр image в начале сообщений вашего блога для предварительного просмотра ваших блогов, как показано ниже. По умолчанию для этого параметра установлено значение false . Если для параметра show_image установлено значение true ваша домашняя страница будет выглядеть следующим образом:
show_tags : вы можете включить или выключить отображение тегов в сообщениях вашего блога, установив для этого значения значение false . По умолчанию для этого параметра установлено значение true , что приводит к отображению следующих ссылок на теги в сообщениях вашего блога следующим образом:
pagination : это максимальное количество сообщений, отображаемых на каждой странице вашей домашней страницы. Любые сообщения, превышающие это количество, будут перенесены на другую страницу. По умолчанию установлено значение 15 . Когда это сработает, вы увидите, что нумерация страниц внизу вашей домашней страницы выглядит следующим образом:
Примечание. Если вы используете более старую версию fastpages, вы не можете использовать процесс автоматического обновления для получения нумерации страниц. Вместо этого вы должны выполнить следующие шаги:
мв index.md index.html
Gemfile и Gemfile.lock в корне вашего репозитория файлами из этого репозитория._config.yml следующим образом (пример посмотрите на _config.yml): gems :
- jekyll-paginate
paginate : 10
paginate_path : /page:num/Альтернативно вы можете скопировать все свои сообщения во вновь созданный репозиторий, созданный на основе шаблона fastpages.
default_badges : по умолчанию значки GitHub, Binder, Deepnote и Colab будут отображаться в сообщениях блога записной книжки. Вы можете изменить эти значения по умолчанию, установив для соответствующего значения в default_badges значение false. Например, если вы хотите отключить значки Binder по умолчанию, вы должны изменить default_badges на следующее:
default_badges :
github : true
binder : false
deepnote : false
colab : true html_escape : позволяет включать и выключать экранирование HTML в различных компонентах сообщений блога. На данный момент вы можете включить это только для поля description в своих сообщениях.
По умолчанию для этого параметра установлено значение false .
Вы можете настроить ширину страницы fastpages на различных устройствах, отредактировав /_sass/minima/custom-variables.scss.
Это значения по умолчанию, которые можно настроить в соответствии с вашими предпочтениями:
// width of the content area
// can be set as "px" or "%"
$content-width : 1000 px ;
$on-palm : 800 px ;
$on-laptop : 1000 px ;
$on-medium : 1000 px ;
$on-large : 1200 px ;hythes.is — это открытая платформа, которая позволяет комментировать и выделять страницы, которые могут быть как общедоступными, так и частными. Когда эта функция включена, читателям вашего блога при выделении текста будет доступна следующая подсказка:
По умолчанию в fastpages это отключено. Вы можете включить или отключить это в файле _config.yml, установив для annotations значение true или false :
# Set this to true to turn on annotations with hypothes.is
annotations : falseВы можете настроить hythes.is, прочитав эти параметры конфигурации. Также полезно прочитать эту документацию, если вы хотите больше работать с гипотезой.is. Однако, прежде чем пытаться настроить эту функцию, вам следует прочитать раздел настройки быстрых страниц, чтобы узнать о важных предостережениях.
Вы можете предложить своим читателям подписаться на RSS-каналы. В Интернете доступно множество служб подписки RSS. Вот некоторые примеры:
fastpages переопределяет стандартную подсветку синтаксиса минимумов в теме Дракулы.
Подсветка по умолчанию на fastpages выглядит так:
Однако вы можете сделать подсветку синтаксиса такой, если захотите:
Если вы хотите вернуться к светлой теме, указанной выше, вы можете удалить строку ниже в _sass/minima/custom-styles.scss.
@import " minima/fastpages-dracula-highlight " ; Если вам не нравится ни одна из этих тем, вы можете добавить свой собственный CSS в _sass/minima/custom-styles.scss . Дополнительные сведения см. в разделе «Настройка fastpages».
В этом сообщении блога описывается, как включить темный режим для быстрых страниц.
Пользователи, предпочитающие использовать систему цитирования BibTeX, могут это сделать; для этого требуется включить плагин jekyll-scholar. Инструкции по реализации этого см. в разделе «Цитаты на Fastpages» через BibTeX и jekyll-scholar.
Поместите комментарий #hide в начале ячейки кода, и он скроет как входные, так и выходные данные этой ячейки.
Комментарий #hide_input вверху любой ячейки скроет только ввод .
Кроме того, расширение Jupyter hide input можно использовать для скрытия ввода или вывода ячеек, что будет учитываться быстрыми страницами.
Возможно, вы захотите скрыть некоторый код в свернутом элементе, который пользователь может развернуть, а не полностью скрывать код от читателя.
#collapse вверху ячейки кода.#collapse_show или #collapse-show вверху ячейки кода.#collapse_output или #collapse-output в верхней части ячейки кода.В ячейке уценки в блокноте используйте следующие ярлыки уценки для встраивания карточек Twitter и видео YouTube.
> youtube: https://youtu.be/your-link
> twitter: https://twitter.com/some-linkДобавление сносок в блокноты немного отличается от уценки. См. Подробное руководство по сноскам в блокнотах.
Сохраните записную книжку, используя соглашение об именовании YYYY-MM-DD-*. в папку /_notebooks или /_word этого репозитория соответственно. Например 2020-01-28-My-First-Post.ipynb . Это соглашение об именах требуется Jekyll для отображения вашего сообщения в блоге.
Будьте внимательны, называя файл правильно! Последнее тире в YYYY-MM-DD- легко забыть. Кроме того, символ, следующий за тире, должен быть только буквой алфавита. Примеры допустимых имен файлов:
2020-01-28-My-First-Post.ipynb
2012-09-12-how-to-write-a-blog.ipynb Если вы не можете правильно назвать свой файл, fastpages автоматически попытается решить проблему, добавив дату последнего изменения вашего файла к созданному сообщению в блоге, однако рекомендуется самостоятельно называть файлы правильно для большей прозрачности.
Зафиксируйте и отправьте файлы на GitHub в главную ветку вашего репозитория.
GitHub автоматически преобразует ваши файлы в сообщения блога. Процесс конвертации займет около 5 минут . Вы можете нажать на вкладку «Действия» вашего репозитория, чтобы просмотреть журналы этого процесса. Будет два рабочих процесса, которые запускаются при каждом нажатии на главную ветку: (1) «CI» и (2) «Состояние страниц GH». Оба рабочих процесса должны завершиться зеленой галочкой для вашего последнего коммита, прежде чем ваш сайт будет обновлен.
При желании вы можете предварительно просмотреть, как будет выглядеть ваш блог локально, прежде чем отправлять его на GitHub. В этом разделе вы найдете подробное руководство по локальному запуску предварительного просмотра.
Если вы пишете сообщение в блоге в уценке, сохраните файл .md в папке /_posts с тем же соглашением об именовании ( YYYY-MM-DD-*.md ), которое указано для блокнотов.
Сохраните документы Microsoft Word в папке /_word с тем же соглашением об именах ( YYYY-MM-DD-*.docx ), которое указано для записных книжек.
Примечание. Замещающий текст в документах Word пока не поддерживается быстрыми страницами и приведет к разрыву ссылок на изображения.
fastpages нет надежного способа указать вступительную часть для документов Word. На данный момент вы можете указать вступительную часть глобально для всех документов Word только путем редактирования _action_files/word_front_matter.txt.
Чтобы указать уникальное начальное содержание для каждого документа Word, вам необходимо вручную преобразовать Word в файлы уценки. Вы можете выполнить действия, описанные в этом сообщении блога, которые помогут вам использовать pandoc для преобразования. Примечание. Если вы хотите настроить запись блога, созданную Word, в уценке, обязательно удалите документ Word из каталога _word, чтобы ваш файл уценки не был перезаписан!
Если вашим основным методом написания сообщений в блоге являются документы Word, и вы планируете всегда вручную редактировать файлы уценки, преобразованные из Word, вам, вероятно, лучше использовать fast_template вместо fastpages.
См. руководство по разработке.
Действие fastpages позволяет конвертировать блокноты из /_notebooks и документы Word из каталогов /_word в вашем репозитории в файлы уценки постов блога, совместимые с Jekyll, расположенные в /_posts . Примечание. Эта структура каталогов в настоящее время негибкая для этого действия, поскольку она предназначена для использования с Jekyll.
Если вы уже достаточно знакомы с Jekyll и хотите использовать эту автоматизацию в своей теме, вы можете использовать это действие GitHub, указав fastai/fastpages@master следующим образом:
...
uses : fastai/fastpages@master
...Наглядный пример того, как может выглядеть полный рабочий процесс:
jobs :
build-site :
runs-on : ubuntu-latest
...
- name : convert notebooks and word docs to posts
uses : fastai/fastpages@master
...
- name : Jekyll build
uses : docker://jekyll/jekyll
with :
args : jekyll build
- name : Deploy
uses : peaceiris/actions-gh-pages@v3
if : github.event_name == 'push'
with :
deploy_key : ${{ secrets.SSH_DEPLOY_KEY }}
publish_branch : gh-pages
publish_dir : ./_siteОбратите внимание, что это действие не имеет обязательных входных данных и выходных переменных .
BOOL_SAVE_MARKDOWN : либо «истина», либо «ложь». Следует ли фиксировать преобразованные файлы уценки из блокнотов и документов Word в каталог _posts вашего репозитория. Это полезно для отладки. по умолчанию: ложьSSH_DEPLOY_KEY : требуется ключ развертывания ssh, если BOOL_SAVE_MARKDOWN = 'true'См. спецификацию API для этого действия в action.yml.
Подробные инструкции по настройке этого блога выходят за рамки данного README. (Мы приглашаем кого-нибудь из сообщества разместить сообщение в блоге о том, как это сделать, в этом репозитории!)
Пожалуйста, ознакомьтесь с руководством по участию.
Пожалуйста, ознакомьтесь с руководством по обновлению.
_posts/ , созданные из моих блокнотов Jupyter или документов Word? О: Рабочий процесс GitHub Actions в этом репозитории преобразует ваши блокноты и документы Word в уценку на лету перед созданием сайта, но никогда не фиксирует эти промежуточные файлы уценки в этом репозитории. Это сделано для того, чтобы избавить вас от раздражения, связанного с постоянной несинхронизацией вашей локальной среды с вашим репозиторием. При желании вы можете просмотреть эти промежуточные файлы уценки, установив входные данные BOOL_SAVE_MARKDOWN и SSH_DEPLOY_KEY для действия fastpages в вашем файле .github/workflows/ci.yaml следующим образом: ...
- name : convert notebooks and word docs to posts
uses : fastai/fastpages@master
with :
BOOL_SAVE_MARKDOWN : true
SSH_DEPLOY_KEY : ${{ secrets.SSH_DEPLOY_KEY }}
... Вопрос: Могу ли я использовать fastpages для сайтов документации Jekyll или для вещей, которые не являются сообщениями в блогах Jekyll? О: На данный момент fastpages — это широко распространенное решение, которое работает только для сообщений в блогах Jekyll. Если вы хотите написать документацию для своего модуля или библиотеки с помощью блокнотов Jupyter, мы предлагаем вам использовать fastai/nbdev, который специально создан для этой цели.
Вопрос: В чем разница между fast_template и fastpages? Какой из них мне следует использовать? О: Поскольку fastpages более гибок и расширяем, мы рекомендуем использовать его там, где это возможно. fast_template может быть лучшим вариантом для людей, ведущих блог, которые вообще не имеют технических знаний и будут создавать сообщения только с помощью встроенного онлайн-редактора Github.
fastpages основан на теме минимумов. Если вы хотите настроить стиль или макет быстрых страниц, вы можете найти инструкции в README минимума. Рекомендуется прочитать полное содержимое README, чтобы понять структуру каталогов. Кроме того, перед настройкой темы рекомендуется иметь базовое представление о Jekyll. Для новичков в Jekyll официальная документация — хорошее начало. Конкретно, вы можете переопределить CSS на fastpages в _sass/minima/custom-styles.scss . ОБРАТИТЕ ВНИМАНИЕ, что функция «скинов» минимума в настоящее время несовместима с настройками CSS fastpages.
Если вы решите внести изменения в быстрые страницы Вполне возможно, что сделанные вами настройки могут противоречить текущим или будущим версиям быстрых страниц, и мы рекомендуем делать это только в том случае, если вы достаточно хорошо разбираетесь в HTML и CSS.
Пожалуйста, ознакомьтесь с руководством по устранению неполадок.
