Como criar um blog usando Github Pages + Obsidian + Quartz
A grande dificuldade de muitos desenvolvedores que estão iniciando é, aonde compartilhar meu conhecimento? Eu crio um blog? Eu uso o Medium? Eu uso o Dev.to? O que fazer? Bom, vamos para a solução mais bonita que é ter seu próprio blog. Claro que eu não vou diminuir quem cria conteúdo em outros lugares, mas centralizar seu conhecimento é a melhor opção.
Vamos lá, o que vamos precisar?
Github Pages
O Github Pages é um serviço do Github que nos possibilita hospedar sites estáticos, normalmente utilizado para hospedar documentação dos projetos nos repositórios git, ele nos possibilita renderizar tanto páginas HTML quanto em Markdown.
Site oficial: https://pages.github.com/
Obsidian
O Obsidian é um aplicativo de anotação, o segredo é que ele gera os arquivo em Markdown uma peça chave para novo propósito. Claro que podemos utilizar, os próprios arquivos .md/.mdx ou usar o Notion, mas isso é outro tutorial.1
Site oficial: https://obsidian.md/
Quartz
O Quartz é um gerador de site estáticos, o pulo do gato é que ele será encarregado de pegar nosso arquivos de anotações gerado em Markdown pelo nosso Obsidian e converterá em HTML, só que ele não faz apenas isso. Ele é customizável e adiciona algumas funcionalidade ao nosso blog como grade de laytout, menus, barra de busca, tema escuro e claro, além de outras customizações que você pode estar fazendo. Se preferir de uma olhada na documentação para mais detalhes e não se esqueça de dar uma estrelinha no repositório do projeto.
Documentação: https://quartz.jzhao.xyz/ - Github: https://github.com/jackyzha0/quartz
Fluxo de Postagem
O fluxo funcionará da seguinte forma: Obsidian > Commit Push > Deploy Github Actions
- Criar/editar seu arquivos no obsidian
- Fazer o commit e fazer o push para seu repositório online
- Rodar pipeline no Github Actions para fazer o deploy das alterações
Configuração do repositório
1 - Para começar primeiramente vamos precisar que você entre no repositório do Quartz e faça um fork do projeto e que o repositório esteja público.
Repositório: https://github.com/jackyzha0/quartz
Nessa parte é essencial que você coloque o nome se seu usuário do github mais sufixo .github.io para que o Github entenda que esse repositório funcionará como um site estático. No meu caso ficará assim, pois já tenho um blog configurado:
meublog.github.io
No seu caso ficará assim:
seunomedeusuario.github.io
2 - Em seu computador faça o clone de seu repositório.
git clone https://github.com/[seu_usuário]/[seu_repositório]
3 - Navegue até pasta de seu projeto e abra ele no seu IDE/Editor de Código.
4 - No terminal e acessando a pasta do projeto, instale as dependências e rode a aplicação para ver se está tudo rodando normalmente.
npm install
npx quartz build --serve
Após o último comando se tudo estiver rodando perfeitamente, ele estará na porta 8080
Agora que nosso blog está rodando, vamos pular para a configuração do Obsidian, depois voltamos para nosso editor e faremos algumas alterações em nosso projeto. Pois como você pode ver, não há conteúdo na pasta /content do nosso repositório e ao tentar cessr receberemos um 404 - Page Not Found.
Configurando o Obsidian
Estou imaginando que você já fez a instalação do Obsidian, se não fez, instale e o configure, não vou me ater a formatação e usabilidade da ferramenta pois já tem bastante conteúdo na internet sobre isso, nosso ponto principal aqui é a criação de um novo cofre.
1- Abra o Obsidian e selecione opção para criar um novo cofre, o qual dedicaremos apenas ao blog.
2 - Após clicar nessa opção, navegue até pasta de nosso projeto/repositório git que fizemos o clone e pelo Obisian selecione a pasta content, isso fará que tudo que criarmos agora em nosso Obsidian será salvo na pasta do nosso projeto onde o Quartz buscará o conteúdo para gerar nosso blog.
Claro que não precisamos usar o Obsidian exclusivamente para fazer edições de markdown, mas estamos optando por ser uma boa interface gráfica para fazer a edição, e claro, se você já tem o costume de usar no seu cotidiano, fica mais fácil.
3 - Para verificar que tudo ocorreu bem, comece criando um arquivo com um conteúdo, crie um arquivo com o nome index pois o Quartz precisa que este arquivo esteja presente. Depois crie um segundo arquivo com o nome de sua preferência
4- Após ter criando alguns arquivos volte para seu editor de código e verifique a pasta content, deve aparecer os arquivos de configuração do Obsidian e os arquivos que você criou.
5 - Agora que os arquivos estão sendo salvos no lugar adequado, vamos conferir o resultado em nosso navegador, recarregue página e veja que nosso blog já está funcionando. Para teste crie novos pasta/arquivos/conteúdo e veja a mágica acontecer.
Removendo arquivos do projeto
Como realizamos um fork do repositório principal, há alguns arquivos que precisamos remover/modificar que não usaremos e que server para gerenciamento do projeto principal. Segue a lista a abaixo:
1 - Remover a pasta docs (opcional) Se você for utilizar para documentar erros que tem no cotidiano ou até mesmo para usar de Zettelkasten para anotações de estudo, você pode deixar.
2 - Editar o README.md (opcional) Se o seu blog ficar público, deixe bem apresentável essa parte, caso queira que outras pessoas se beneficiem do código e como fazer para rodá-lo.
3 - Remover todos os arquivos da pasta .github
Configurando Github Pages
Agora vamos realizar a configuração do Github Pages para que possamos publicar nosso blog estático online, siga os passos a baixo.
1 - Entre em seu repositório, e em seguida vá na aba Settings
2 - No menu lateral esquerdo, na seção Code and automation clique na aba Pages.
3 - Na página do Github Pages você deve fazer alguma configurações, a primeira e mais importante é selecionar a origin em nosso Build and deployment no nosso caso estaremos utilizando o Github Actions, por isso o selecione.
4 - Agora vamos configurar o arquivos de build e deploy, em nosso editor, vá na pasta .github crie uma pasta chamada workflows e depois crie um arquivo dentro dessa pasta chamado deploy.yml.
4 - Agora cole o seguinte conteúdo dentro do arquivo deploy.yml, esse arquivo contém as configurações de build e deploy de nosso blog, elas são utilizadas pelo Github Actions, é como se fosse uma receita de bolo para nossa pipeline para o que deve fazer sempre que tiver alguma alteração. Para mais informações e detalhes você pode estar lendo a documentação:
GitHub Actions: https://github.com/features/actions
Github Pages: https://pages.github.com/
Quartz: https://quartz.jzhao.xyz/hosting
name: Deploy Quartz Site to GitHub Pages
on:
push:
branches:
- main
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # Fetch all history for git info
- uses: actions/setup-node@v3
with:
node-version: 18.14
- name: Install Dependencies
run: npm ci
- name: Build Quartz
run: npx quartz build
- name: Upload artifact
uses: actions/upload-pages-artifact@v2
with:
path: public
deploy:
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
5 - Depois do passo anterior faça o commit das alterações realizadas e envie para o Github
git add -A
git commit -m "Added: Settings on Github Actions"
git push
6 - Se você entende um pouco do Github Actions, dê uma olhada no arquivo. Percebeu que nosso Gihub Actions não foi executado? Isso ocorreu porque quando você faz o fork do repositório principal a branch principal do repositório é a v4, para deixarmos como principal a branch main vamos criar um nova branch.
git branch main
git checkout main
git push origin main
7 - Entrando na aba actions do repositório você verá que nosso action foi executada, porém no passo de deploy ocorreu um erro.
8 - Para corrigir isso vamos definir a branch main como nossa branch principal. Na opção Default branch escolha a main, selecionando a opção switch to another branch
9 - Depois de criada e definida como principal a branch main, você deve ir na aba Settings e selecionar a seção Environments haverá uma já criada, exclua ela para que possamos criar outra, pois a atual está configurada para a branch antiga a v4.
10 - Agora que não há nenhum ambiente configurado clique em New environment
11 - Agora de um nome ao seu ambiente, no meu caso estou dando o nome de: github-pages
12 - Após criado seu ambiente, precisamos definir a branch para esse ambiente. Faça isso dentro do ambiente que foi criado no passo anterior, na seção Deployment branches and tags clique no botão No restriction e depois selecione Selected branchs and tags.
13 - Agora adicione a branch main clicando na opção Add deployment branch or tag rule
14 - Como último passo, volte até a aba Actions do seu repositório então selecione o workflow que deu falha
15 - No canto superior direito clique em Re-run jobs então selecione a opção Re-run all jobs, então seus trabalhos serão executados novamente.
Parabéns seu blog foi publicado!
Para acessar, clique no link mostrado no card do deploy, agora é só seguir o fluxo de alteração e ir publicando em seu blog. Para saber como personalizar seu blog de uma olhada na documentação do Quartz.