Настройка публикации: notes (private) → knowledge (public) → Pages¶

Заметки пишутся в приватном репозитории notes. При каждом push GitHub Actions собирает сайт через MkDocs Material и публикует его в публичный репозиторий knowledge, откуда его раздаёт GitHub Pages.

notes (private, Markdown)
   │  git push
   ▼
GitHub Actions: mkdocs build
   │  push собранного сайта
   ▼
knowledge (public, gh-pages branch)
   │  GitHub Pages
   ▼
https://<username>.github.io/knowledge/

Где живёт настройка Actions¶

Отдельной страницы настроек для этого нет — GitHub Actions управляется самим yaml-файлом в репозитории:

notes/
├── requirements.txt
└── .github/
    └── workflows/
        └── publish.yml

Всё, что лежит в .github/workflows/, GitHub подхватывает автоматически и показывает во вкладке Actions репозитория. Отдельно "включать" Actions не нужно — достаточно, чтобы файл там был.

Что понадобится¶

Приватный репозиторий notes — исходники (mkdocs.yml, docs/, requirements.txt, .github/workflows/publish.yml).
Публичный репозиторий knowledge — пустой, туда будет пушиться результат сборки (GitHub Pages бесплатно работает только с публичных репозиториев).

Шаги настройки (один раз)¶

1. Создать публичный репозиторий `knowledge`¶

Пустой репозиторий, можно с одним README. Ничего в нём вручную делать не нужно — Actions будет пушить туда сам.

2. Создать токен доступа¶

GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.

Repository access: Only select repositories → knowledge
Permissions: Contents → Read and write

Скопировать токен — он показывается один раз.

3. Добавить токен как секрет в `notes`¶

В репозитории notes: Settings → Secrets and variables → Actions → New repository secret.

Name: NOTES_DEPLOY_TOKEN
Value: токен из шага 2

4. Проверить requirements.txt¶

Файл requirements.txt в корне notes обязателен — без него шаг setup-python с cache: pip падает с ошибкой No file ... matched to [**/requirements.txt or **/pyproject.toml].

mkdocs-material

Полное содержимое `.github/workflows/publish.yml`¶

name: Publish knowledge base

on:
  push:
    branches: [main]
  workflow_dispatch:   # ручной запуск кнопкой из вкладки Actions

permissions:
  contents: read

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout notes (private)
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip
          cache-dependency-path: requirements.txt

      - name: Install MkDocs Material
        run: pip install -r requirements.txt

      - name: Build site
        run: mkdocs build --strict

      - name: Deploy to public repo (knowledge)
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.NOTES_DEPLOY_TOKEN }}
          external_repository: dessanhemrayev/knowledge
          publish_branch: gh-pages
          publish_dir: ./site
          commit_message: "publish: ${{ github.event.head_commit.message }}"

Если репозиторий knowledge называется иначе или принадлежит другому аккаунту — поменять значение external_repository.

5. Запушить и проверить¶

git add .
git commit -m "init"
git push

Открыть вкладку Actions в notes — workflow Publish knowledge base должен пройти зелёным.

6. Включить Pages в публичном репозитории¶

В репозитории knowledge: Settings → Pages.

Source: Deploy from a branch
Branch: gh-pages / / (root)
Save

Через минуту сайт доступен на https://<username>.github.io/knowledge/.

Как это выглядит дальше¶

Дальше публикация полностью автоматическая: пишете .md в notes любым удобным способом (Obsidian + obsidian-git, github.dev, мобильное приложение GitHub) → push в main → через 1–2 минуты обновлённая версия уже на сайте. Исходники в notes остаются приватными, наружу виден только собранный knowledge.

Возможные проблемы¶

Симптом	Причина
`Error: No file ... matched to [**/requirements.txt ...]`	нет `requirements.txt` в корне `notes`, или в шаге `setup-python` включён `cache: pip` без него
Actions зелёный, но сайт 404	в `knowledge` ещё не включён Pages, или указана не та ветка (`gh-pages`)
`Permission denied` при деплое	токен `NOTES_DEPLOY_TOKEN` истёк, отозван, или у него нет прав Contents: Read and write на `knowledge`
Сайт не обновляется	проверить, что push действительно ушёл в ветку `main` (или ту, что указана в `on: push: branches:`)