Develop webdesign like 2009

.devcontainer/devcontainer.json

@@ -5,8 +5,12 @@
       "extended": true,
       "version": "0.147.9"
     },
-    "ghcr.io/devcontainers/features/node:1": {}
+    "ghcr.io/devcontainers/features/node:1": {},
+    "ghcr.io/devcontainers/features/ruby:1": {
+      "version": "3.3"
+    }
   },
+  "postCreateCommand": "bundle install",
   "customizations": {
     "vscode": {
       "extensions": [

.github/workflows/lint.yaml

@@ -0,0 +1,22 @@
+name: Lint Markdown
+
+on:
+  pull_request:
+  push:
+    branches: [develop, main]
+
+jobs:
+  mdl:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Rodar mdl
+        run: bundle exec mdl content README.md

.github/workflows/release.yaml

@@ -0,0 +1,77 @@
+name: Release
+
+# Roda sempre que develop é mergeada em main (ou qualquer outro push direto
+# em main). Gera o CHANGELOG.md (Keep a Changelog) com o git-cliff, cria a
+# tag semver automaticamente e publica a GitHub Release com as notas.
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Instalar git-cliff
+        uses: taiki-e/install-action@git-cliff
+
+      - name: Verificar se há algo para lançar
+        id: release
+        run: |
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          NEXT_VERSION=$(git-cliff --bumped-version 2>/dev/null)
+
+          if [ -n "$LAST_TAG" ] && [ "$LAST_TAG" = "$NEXT_VERSION" ]; then
+            echo "Nada para lançar (nenhum commit relevante desde $LAST_TAG)."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Próxima versão: $NEXT_VERSION"
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+            echo "version=$NEXT_VERSION" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Atualizar CHANGELOG.md
+        if: steps.release.outputs.skip == 'false'
+        run: git-cliff --tag "${{ steps.release.outputs.version }}" -o CHANGELOG.md
+
+      - name: Commitar CHANGELOG.md
+        if: steps.release.outputs.skip == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add CHANGELOG.md
+          git commit -m "chore(release): ${{ steps.release.outputs.version }}"
+          git push origin HEAD:main
+
+      - name: Criar tag
+        if: steps.release.outputs.skip == 'false'
+        run: |
+          git tag "${{ steps.release.outputs.version }}"
+          git push origin "${{ steps.release.outputs.version }}"
+
+      - name: Gerar notas da release
+        if: steps.release.outputs.skip == 'false'
+        run: |
+          git-cliff --tag "${{ steps.release.outputs.version }}" --latest --strip header \
+            -o /tmp/release-notes.md
+
+      - name: Publicar GitHub Release
+        if: steps.release.outputs.skip == 'false'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ steps.release.outputs.version }}" \
+            --title "${{ steps.release.outputs.version }}" \
+            --notes-file /tmp/release-notes.md

.gitpod.yml

@@ -10,6 +10,10 @@ tasks:
     init: echo "Your version of Hugo is `hugo version`" && hugo mod tidy
     command: hugo server -D -F --baseURL $(gp url 1313) --liveReloadPort=443 --appendPort=false --bind=0.0.0.0 --disableFastRender
 
+  - name: Lint (mdl)
+    init: bundle install
+    command: bundle exec mdl content README.md
+
 ports:
   - port: 1313
     onOpen: open-preview

.mdl_style.rb

@@ -0,0 +1,16 @@
+all
+
+# O <h1> de cada post vem do front matter (`title`), renderizado pelo tema
+# Hextra — o corpo do markdown propositalmente começa em "##".
+exclude_rule "MD002" # first header should be a top level header
+exclude_rule "MD041" # first line in a file should be a top level header
+
+# Prosa, não código — não faz sentido impor um limite fixo de coluna.
+exclude_rule "MD013" # line length
+
+# `goldmark.unsafe: true` no hugo.yaml permite HTML puro nos posts de propósito.
+exclude_rule "MD033" # inline HTML
+
+# Prefere numeração sequencial (1. 2. 3.) em vez do padrão do mdl (1. 1. 1.).
+rule "MD029", :style => :ordered
+

.mdlrc

@@ -0,0 +1 @@
+style "#{File.dirname(__FILE__)}/.mdl_style.rb"

Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem "mdl", "~> 0.18"

Gemfile.lock

@@ -0,0 +1,48 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    chef-utils (19.3.15)
+      concurrent-ruby
+    concurrent-ruby (1.3.8)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    mdl (0.18.1)
+      kramdown (~> 2.5)
+      kramdown-parser-gfm (~> 1.1)
+      mixlib-cli
+      mixlib-config
+      mixlib-shellout
+      uri
+    mixlib-cli (2.1.8)
+    mixlib-config (3.0.27)
+      tomlrb
+    mixlib-shellout (3.4.10)
+      chef-utils
+    rexml (3.4.4)
+    tomlrb (2.0.4)
+    uri (1.1.1)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  mdl (~> 0.18)
+
+CHECKSUMS
+  chef-utils (19.3.15) sha256=1c537a9c85b55b6d897de8e8af6b66b017a6dfae2b5e7b25e0bf320637e0b86a
+  concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  kramdown (2.5.2) sha256=1ba542204c66b6f9111ff00dcc26075b95b220b07f2905d8261740c82f7f02fa
+  kramdown-parser-gfm (1.1.0) sha256=fb39745516427d2988543bf01fc4cf0ab1149476382393e0e9c48592f6581729
+  mdl (0.18.1) sha256=14c7ab8264bbeac4010bd54adb5d125cf1d29b3848c3b6bfacb239b8bc70037a
+  mixlib-cli (2.1.8) sha256=e6f27be34d580f6ed71731ca46b967e57793a627131c1f6e1ed2dad39ea3bdf9
+  mixlib-config (3.0.27) sha256=d7748b1898e4f16502afec1de00b5ad65c6de405114b1b0c65ec61b1a9100148
+  mixlib-shellout (3.4.10) sha256=7c8a6c5a6c90922a8871ed682129c19c9b1a514eedea2e867077229e6a415f0c
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  tomlrb (2.0.4) sha256=262f77947ac3ac9b3366a0a5940ecd238300c553e2e14f22009e2afcd2181b99
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
+
+BUNDLED WITH
+  4.0.16

README.md

@@ -10,15 +10,79 @@ Programming and Quality. This is not a tutorials. This is my daily study, buildi
 Well ok. Where from this idea? Good, this ideia emerge from the book The Programatic Programmer.
 Specifically, of the chapter one [get to know the book here](https://www.amazon.com.br/Programador-Pragm%C3%A1tico-Aprendiz-Mestre/dp/8577807002).
 
-## Clone Runner and Testing
+## Testando localmente
+
+**Pré-requisitos:** [Hugo extended](https://gohugo.io/installation/) `0.147.9`+
+e [Go](https://go.dev/dl/) (só é usado pra baixar o tema via Hugo Modules,
+não tem código Go no projeto). Se preferir não instalar nada na sua máquina,
+o repo já vem pronto pra abrir num Dev Container (`.devcontainer/`) ou no
+[Gitpod](https://gitpod.io/#https://github.com/kellen-xavier/ladydebug.github.io) —
+os dois sobem o ambiente completo (Hugo, Go, Ruby) sozinhos.
 
 ```bash
 git clone https://github.com/kellen-xavier/ladydebug.github.io.git
+cd ladydebug.github.io
 
-cd ladydebug.github. io
-
+# baixa o tema (Hextra) via Hugo Modules
 hugo mod tidy
 
+# sobe o servidor local com live reload
 hugo server -D -F
+```
 
+Abra [http://localhost:1313/](http://localhost:1313/). `-D` mostra posts marcados como `draft: true`
+e `-F` mostra posts com data no futuro — assim dá pra revisar tudo antes de
+publicar. Qualquer mudança em `content/`, `layouts/`, `assets/` ou
+`data/` recarrega a página sozinha.
+
+Antes de abrir um PR, vale rodar também o [lint](#lint-de-markdown) e um build
+de produção igual ao do CI, pra pegar erro de template que só aparece com
+`--minify`:
+
+```bash
+hugo --gc --minify
+```
+
+## Lint de Markdown
+
+Os posts são checados com o [`mdl`](https://github.com/markdownlint/markdownlint) (regras em
+`.mdl_style.rb`). Roda automaticamente em todo PR e push para `develop`/`main`
+(`.github/workflows/lint.yaml`); para rodar localmente:
+
+```bash
+bundle install
+bundle exec mdl content README.md
 ```
+
+## Changelog e releases
+
+O `CHANGELOG.md` (formato [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)) é gerado
+automaticamente pelo [`git-cliff`](https://git-cliff.org/) a partir dos commits em
+[Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, ...). Não é para
+editar esse arquivo manualmente.
+
+Quando `develop` é mergeada em `main`, o workflow `.github/workflows/release.yaml`:
+
+1. calcula a próxima versão a partir dos commits desde a última tag;
+2. atualiza o `CHANGELOG.md` e commita em `main`;
+3. cria a tag `vX.Y.Z` e publica a GitHub Release com as notas dessa versão.
+
+Se não houver commit relevante (`feat`/`fix`/...) desde a última tag, nada é publicado.
+
+## Doca (dock) do rodapé
+
+Barra fixa no rodapé com janelas flutuantes (`<dialog>`, arrastáveis, sem
+libs), no estilo desktop/OS do fim dos anos 2000. Fica isolada do resto do
+tema em arquivos próprios:
+
+- `data/dock.yaml` — quais botões existem, rótulo, ícone e link do Spotify.
+- `data/events.yaml` — lista de próximos eventos do painel "Calendário".
+- `content/drafts/` — rascunhos (`hugo new drafts/nome.md`); cada um vira uma
+  página própria, mas fica fora do blog, do RSS e do sitemap.
+- `assets/css/desktop-dock.css` e `assets/js/desktop-dock.js` — estilo e
+  comportamento, separados do `custom.css`/tema.
+
+Pra trocar o link do Spotify ou adicionar um evento, é só editar os `.yaml`
+acima — não precisa mexer nos templates.
+
+Ícones: [Pixelarticons](https://github.com/halfmage/pixelarticons) (MIT).