cortexjs.io

Этот репо содержит исходные файлы для веб -сайта "cortexjs.io".

TL; DR

Впервые после клонирования проекта или после внесения некоторых изменений источника

git submodule init

git submodule update

# Setup, make a dev build and start a server
npm start

Чтобы обновить документацию после нового выпуска

 # Pick-up changes in the dependent modules
npm run update

# Generate .md files for API and launch local server
npm start

Для постановки и развертывания обновления

npm run stage
# Make a clean production build.
# Output goes inside submodules/cortex-js.github.io

npm run restart
# Validate that everything works well in the browser then...

npm run deploy
# submodules/cortex-js.github.io (a git submodule) gets pushed to cortex-js.github.io

Архитектура

Сайт опубликован с использованием страниц GitHub. Основным преимуществом использования страниц GH является интеграция рабочих процессов (Pubshing to gh запускает автоматическое обновление обслуживаемого сайта)

Содержание сайтов авторируется в основном в виде файлов разметки, обрабатываемых с eleventy , чтобы превратить их в HTML/CSS.

Основная eleventy конфигурации находится в файле config/eleventy.js , включая определение разметки для использования.

Двигатель Markdown-это markdown-it , который реализует Commonmark.

Плагин mardown-it-attrs позволяет стиль абзацев, например,

Это уведомление. {.notice- Info}

Плагин markdown-it-deflist поддерживает списки определения стиля PANDC:

 Term 1
:   Definition 1
:   Second definition

Вывод находится в каталоге submodules/cortex-js.github.io . Этот каталог является подмодуль GIT, который связан с cortex-js.github.io Repo. Этот репо является той, что опубликовано GH Pages (для организации можно опубликовать только целое репо, для проектов содержание может быть содержатся в каталоге A /docs ).

Смотрите также подмодули.

cortex-js.github.io Repo также должна включать два дополнительных файла:

• .nojekyll , который указывает на GitHub, что он не должен обрабатывать содержание этого репо с Jekyll (поскольку это уже вывод Jekyll)
• CNAME с содержанием cortexjs.io

Эти файлы создаются при запуске npm run stage .

Используйте вкладку «Настройки» в репозите cortex-js.github.io , чтобы указать использование пользовательского домена.

Кроме того, записи DNS для cortexjs.io должны включать следующее:

• Запись Cname, которая указывает на www.cortex-js.io на cortex-js.io
• Четыре записи, которые указывают на
  • 185.199.108.153
  • 185.199.109.153
  • 185.199.110.153
  • 185.199.111.153

Содержание

Команда npm run build генерирует документацию для API из файла TypeScript .d.ts в каталог build/ каталога.

Процесс сборки использует инструмент typedoc для анализа файлов заголовка API и вывода файлов json в каталоге build/ каталога.

ПРИМЕЧАНИЕ. Чтобы отладить конвертер, используйте отладчик VSCODE. Выберите «Отладка»> «Начните отладку», чтобы начать сеанс отладки прямо в VSCODE.

Затем скрипт build-guides преобразует файл json в Markdown в каталоге ./src/build , который затем может быть обработан на одиннадцать с помощью npm run build или npm start .

Информация о стиле CSS определяется в src/_sass/ .

Документация API должна следовать руководству по стилю документации Google (https://developers.google.com/style/api-reference-comments) и https://developers.google.com/style

Кроме того, код TypeScript должен следовать руководству по стилю Google: https://google.github.io/styleguide/jsguide.html#naming

Настройка и сценарии

Проект следует по стандарту GitHub для сценариев проекта именования.

Чтобы сделать местную сборку:

npm start

Чтобы сделать сборку, готовую к постановке:

npm run stage

Тест

«Тестирование» сгенерированного сайта состоит из проверки ссылок и что сгенерированный HTML действителен.