Уютный блог на HUGO

Рассмотрим, как поднять, захостить и настроить деплой блога на Hugo, не потратив ни копейки (или почти).

Бесплатный хостинг и деплой блога на Hugo

Не путайте Hygge и Hugo

Hygge — датское слово, обозначающее уют и тепло. Hugo — генератор статических страниц, который обеспечивает комфорт в работе.

Hugo — наш уютный друг

Hugo генерирует статические HTML-файлы. Мы размещаем текст в формате Markdown и изображения в нужных папках, а Hugo собирает из них готовые страницы.

Установка и первый старт

Установите git и Hugo. Для Fedora 36: sudo dnf update sudo dnf install git hugo Для других ОС смотрите документацию Hugo.
Инициализируйте новый блог для хостинга на GitHub Pages (нужен аккаунт и репозиторий <username>.github.io):

    hugo new site <username>.github.io
    cd <username>.github.io

Создайте .gitignore, чтобы исключить папку /public:

    echo "/public" > .gitignore

Инициализируйте Git-репозиторий:

    git init
    git branch -M main
    git remote add origin git@github.com:<username>/<username>.github.io.git

Базовый проект готов, но он пока без темы.

Настройка темы

Выберите тему, например, PaperMod. Установите её:

    git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
    git submodule update --init --recursive

Настройте тему, создав файл config.yml:

    rm config.toml
    vim config.yml

Добавьте настройки (пример для PaperMod):

    baseURL: "https://username.github.io/"
    title: My new site
    paginate: 10
    theme: PaperMod

    enableRobotsTXT: true
    buildDrafts: false
    buildFuture: false
    buildExpired: false

    minify:
     disableXML: true
     minifyOutput: true

    params:
     env: production
     title: ExampleSite
     description: "This is long-long description..."
     keywords: [Blog, Portfolio, PaperMod]
     author: My name there
     DateFormat: "January 2, 2006"
     defaultTheme: auto
     disableThemeToggle: false
     ShowReadingTime: true
     ShowPostNavLinks: true
     ShowCodeCopyButtons: true
     ShowWordCount: true
     ShowRssButtonInSectionTermList: true
     UseHugoToc: true
     disableSpecial1stPost: false
     disableScrollToTop: false
     hidemeta: false
     hideSummary: true
     showtoc: false
     tocopen: false

    assets:
     favicon: "<link / abs url>"
     favicon16x16: "<link / abs url>"
     favicon32x32: "<link / abs url>"
     apple_touch_icon: "<link / abs url>"
     safari_pinned_tab: "<link / abs url>"

    label:
     text: "Home"
     icon: /apple-touch-icon.png
     iconHeight: 35

   profileMode:
     enabled: false
     title: ExampleSite
     subtitle: "This is subtitle"
     imageUrl: "<img location>"
     imageWidth: 120
     imageHeight: 120
     imageTitle: my image
   
    buttons:
       - name: Posts
         url: posts
       - name: Tags
         url: tags

   homeInfoParams:
     Title: "Hi there \U0001F44B"
     Content: Welcome to my blog

   socialIcons:
     - name: twitter
       url: "https://twitter.com/"
     - name: stackoverflow
       url: "https://stackoverflow.com"
     - name: github
       url: "https://github.com/"

   cover:
     hidden: true
     hiddenInList: true
     hiddenInSingle: true

   fuseOpts:
     isCaseSensitive: false
     shouldSort: true
     location: 0
     distance: 1000
     threshold: 0.4
     minMatchCharLength: 0
     keys: ["title", "permalink", "summary", "content"]

   menu:
     main:
       - identifier: categories
         name: categories
         url: /categories/
         weight: 10
       - identifier: tags
         name: tags
         url: /tags/
         weight: 20
       - identifier: example
         name: example.org
         url: https://example.org
         weight: 30

    pygmentsUseClasses: true

    markup:
        highlight:
        noClasses: false

Проверьте результат:

hugo server

Блог доступен по адресу localhost:1313.

Создание первой записи

Создайте папку для поста:

    mkdir -p content/posts/first-post
    vim content/posts/first-post/index.md

Добавьте шаблон поста:

   ---
   title: "My 1st post"
   date: 2022-12-08T11:30:03+00:00
   tags: ["first"]
   author: "Me"
   showToc: true
   TocOpen: false
   draft: false
   hidemeta: false
   comments: false
   description: "Desc Text."
   canonicalURL: "https://canonical.url/to/page"
   disableHLJS: true
   disableShare: false
   hideSummary: false
   searchHidden: true
   ShowReadingTime: true
   ShowBreadCrumbs: true
   ShowPostNavLinks: true
   ShowWordCount: true
   ShowRssButtonInSectionTermList: true
   UseHugoToc: true
   cover:
       image: "<image path/url>"
       alt: "<alt text>"
       caption: "<text>"
       relative: false
       hidden: true
   editPost:
       URL: "https://github.com/<path_to_repo>/content"
       Text: "Suggest Changes"
       appendFilePath: true
---

Проверьте блог:

hugo server

Деплой на GitHub Pages

Настройте Git: git config –global user.name “” git config –global user.email “”
Сгенерируйте SSH-ключи:

   ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f deployment -N ""

Добавьте публичный ключ в GitHub:
- В репозитории: Settings → Deploy Keys → Add Deploy Key.
- Скопируйте ключ: cat deployment.pub.
- Включите Allow write access.
Добавьте приватный ключ в секреты:
- Settings → Secrets → Actions → New Repository Secret.
- Имя: ACTIONS_DEPLOY_KEY.
- Скопируйте: cat deployment.
Настройте права Actions:
- Actions → General → Workflow permissions → Read and write permissions.
Создайте GitHub Action:

   mkdir -p .github/workflows
   vim .github/workflows/gh-pages.yml

Вставьте: name: GitHub Pages on: push: branches: - main jobs: build-deploy: runs-on: ubuntu-latest concurrency: group: ${{ github.workflow }}-${{ github.ref }} steps: - name: Checkout uses: actions/checkout@v3 with: submodules: true fetch-depth: 0 - name: Setup Hugo uses: peaceiris/actions-hugo@v2 with: hugo-version: “latest” extended: true - name: Build run: hugo –minify - name: Deploy uses: peaceiris/actions-gh-pages@v3 if: ${{ github.ref == ‘refs/heads/main’ }} with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_branch: gh-pages publish_dir: ./public

Запушьте изменения:

   git add . && git commit -m "Init" && git push -u origin main

Настройте Pages:
- Settings → Pages → Build and deployment.
- Выберите Deploy from a branch, ветка gh-pages.
Проверьте блог по адресу <username>.github.io.

Использование своего домена

Купите домен (например, на beget.com).
Настройте DNS:
- Добавьте A и AAAA записи (IP-адреса из GitHub Pages).
- Удалите дефолтные записи.
- Для www добавьте CNAME на <yourdomen.com>.
Создайте файл static/CNAME:

   echo "<yourdomen.com>" > static/CNAME

Настройте домен в GitHub:
- Settings → Pages → Custom domain.
- Впишите <yourdomen.com>.
Если TLS-сертификат не подхватился:
- В DNS: для www.<yourdomen.com> укажите CNAME на <username>.github.io.
- Удалите кастомный домен в GitHub, подождите 5 минут, добавьте заново <yourdomen.com>.

Кастомные Shortcode

Для вставки Bandcamp-плеера создайте шорткод:

Создайте файл:

   mkdir -p layouts/shortcodes
   vim layouts/shortcodes/bandcamp.html

Добавьте код:

   {{- $id := .Get "id" -}}
   {{- with .Get "type" -}}
   {{- if eq . "track" -}}
   <div style="margin: 0px 10px 10px 10px;">
     <iframe
       style="border: 0; width: 350px; height: 350px;"
       src="https://bandcamp.com/EmbeddedPlayer/track={{ $id }}/size=large/bgcol=333333/linkcol=9a64ff/minimal=true/transparent=true/"
     >
     </iframe>
   </div>
   {{- else if eq . "album" -}}
   <div style="margin: 0px 10px 10px 10px;">
     <iframe
       style="border: 0; width: 350px; height: 350px;"
       src="https://bandcamp.com/EmbeddedPlayer/album={{ $id }}/size=large/bgcol=333333/linkcol=9a64ff/minimal=true/transparent=true/"
     >
     </iframe>
   </div>
   {{- end -}}
   {{- end -}}

Используйте в Markdown:

   {{< bandcamp id="3756810824" type="track" >}}

Кастомные страницы

Для страницы с музыкой:

Создайте файл:

   mkdir -p content/music
   vim content/music/index.md

Добавьте:

   ---
   title: "Music"
   Description: "Music page"
   layout: "music"
   ---
   {{< bandcamp id="3756810824" type="track" >}}
   {{< bandcamp id="1062007976" type="album" >}}

Создайте шаблон:

   mkdir -p layouts/page
   vim layouts/page/music.html

Добавьте:

   {{ define "main" }}
   <main id="main-content" class="grow">
       <header>
           <h1 class="mt-0 text-4xl font-extrabold text-neutral-900 dark:text-neutral">Music</h1>
       </header>
       <section class="flex flex-wrap -mx-2 place-content-center overflow-hidden">
           <div class="container my-3">
               <div class="row">
                   <div class="flex flex-wrap">{{ .Content }}</div>
               </div>
           </div>
       </section>
   </main>
   {{ end }}

Добавьте в меню (config.yml):

   [[main]]
     name = "Music"
     pageRef = "music"
     weight = 20

Упрощение деплоя

Создайте алиас для пуша изменений:

Откройте ~/.zshrc (или ~/.bashrc):

   vim ~/.zshrc

Добавьте:

   alias post-save="git add . && git commit -m \"Added new post\" && git push"

Примените:

   source ~/.zshrc

Используйте:

   post-savepandoc -s -r html https://owlpaw.com/blog/hugo-simple-blog/ -o example12.md

Рассмотрим, как поднять, захостить и настроить деплой блога на Hugo, не потратив ни копейки (или почти).#

Не путайте Hygge и Hugo#

Hugo — наш уютный друг#

Установка и первый старт#

Настройка темы#

Создание первой записи#

Деплой на GitHub Pages#

Использование своего домена#

Кастомные Shortcode#

Кастомные страницы#

Упрощение деплоя#