![\"Foto](\"https://image.tmdb.org/t/p/w1920/3ObqsNzAOOZoK0K98KKtTeYP1uV.jpg\")
Descobri por acaso a série Halt and Catch Fire navegando pelo Reddit, e comecei a assistir por conta do trama ser relacionado a tecnologia. Não esperava que ia me deparar com uma série tão boa, me surpreende que não seja tão comentada.
\nPode-se dizer que essa série é a “irmã” dramática da série de comédia da HBO Silicon Valley, que também é ótima, por sinal. HaCF é bem mais direta ao ponto e mais “pé no chão” se você comparar com a outra série famosa da área: Mr. Robot.
\nEu já assisti vários filmes sobre a história da tecnologia, sendo todos eles em geral biografias ou baseados em fatos reais. HaCF não é exatamente baseado nos fatos reais, mas muitos dos acontecimentos são baseados neles.
\nPor exemplo, a primeira temporada, que é excelente, é sobre o desenvolvimento de um clone do IBM PC. Na série, a empresa que os personagens trabalham, a Cardiff Electric, é a que está fazendo a P&D, enquanto na vida real foi a finada Compaq.
\nOs personagens também são muito carismáticos, e boa parte do uso de tecnologia é verídico. Foi bem legal ver algumas cenas com o Gordon programando em um Commodore 64 com a linguagem C, usando o livro “The C Programming Language”. Como uma pessoa da área, estou me divertindo pra caramba com a tecnologia da época sendo mostrada e usada.
\nAinda não terminei de assistir todos os episódios, mas o que vi até agora tem um alto valor de produção. O bom também é que a série foi finalizada com 4 temporadas, cada uma com 10 episódios. Atualmente estamos acostumados a ver o lançamento das temporadas em streamings sem sequer saber se a série será renovada ou cancelada, então saber que ela foi planejada e terminada é um alívio.
","date_published":"2026-06-20T00:00:00.000Z","date_modified":"2026-06-21T11:29:00.000Z","tags":["Televisão"],"language":"pt-BR"},{"id":"criando-um-feed-rss-com-nuxt-content","url":"https://alessandrojean.github.io/post/criando-um-feed-rss-com-nuxt-content","title":"Criando um feed RSS com Nuxt Content","summary":"Um passo-a-passo simples em como criar um feed e também disponibilizar o HTML dos posts.","content_html":"Disponibilizar um feed RSS quando você está utilizando o Nuxt Content não é difícil, mas você pode acabar encontrando alguns obstáculos no caminho.
\nIremos começar criando a rota no servidor que irá disponibilizar o RSS. Normalmente é conveniente colocar o feed no mesmo caminho que seu conteúdo está. Por exemplo, se sua lista de posts fica em /blog, o caminho /blog/feed.xml é uma boa escolha.
Usando o Nuxt, podemos criar essa rota ao criar o arquivo server/routes/blog/feed.xml.get.ts.
Cuidado:
Esta não é uma rota de API, então não deve ser colocada em /server/api.
O esqueleto do arquivo é basicamente este:
\nimport { queryCollection } from '@nuxt/content/server';\n\nexport default defineEventHandler(async (event) => {\n const posts = await queryCollection(event, 'blog')\n .order('created_at', 'DESC')\n .limit(10)\n .all();\n\n return posts;\n});\nO que queremos fazer é manipular as postagens tal que a rota na verdade retorne um feed RSS válido. Podemos usar o pacote rss para nos ajudar, já que ele contém um construtor de RSS que facilita as coisas.
\nNós iremos usar a classe RSS.
import RSS from 'rss';\nPara começar, precisamos criar o feed e colocar algumas informações básicas.
\nconst url = 'https://exemplo.org';\n\nconst feed = new RSS({\n title: 'Blog de exemplo',\n description: 'Somente um blog.',\n site_url: url,\n feed_url: `${url}/blog/feed.xml`,\n language: 'pt-BR',\n custom_elements: [\n { icon: `${url}/img/apple-touch-icon.png` },\n ],\n custom_namespaces: {\n content: 'http://purl.org/rss/1.0/modules/content/',\n dc: 'http://purl.org/dc/elements/1.1/',\n sy: 'http://purl.org/rss/1.0/modules/syndication/',\n },\n});\nAlgumas das propriedades são bem diretas. Outras são só complementos, como a custom_namespaces, que permite que o XML gerado tenha tags extras que não estão na especificação do RSS.
Como nós temos uma lista de postagens, podemos iterar sobre ela e criar cada item do feed.
\nfor (const post of posts) {\n feed.item({\n title: post.title,\n guid: `${url}/post/${post.path}`,\n url: `${url}/post/${post.path}`,\n description: post.description,\n date: new Date(post.created_at),\n categories: post.category ? [post.category] : undefined,\n custom_elements: [\n { 'dc:creator': { _cdata: 'Fulano de Tal' } },\n ],\n });\n}\nAgora que o feed está completo, podemos definir o cabeçalho Content-Type.
setResponseHeader(event, 'Content-Type', 'text/xml');\nEntão nós podemos finalmente retornar o feed XML.
\nreturn feed.xml();\nComo exemplo, você pode dar uma olhada no RSS deste site.
\nSe seu site usa um deploy com um servidor, já está tudo certo. Mas, se usa um deploy como site estático, como o GitHub Pages, você precisa de uma etapa adicional.
\nPrecisamos informar ao Nuxt para também pré-renderizar esta rota do servidor durante o build. Isso pode ser feito editando a propriedade nitro no arquivo nuxt.config.ts.
export default defineNuxtConfig({\n nitro: {\n prerender: {\n routes: ['/blog/feed.xml'],\n },\n },\n});\nVocê pode por um link para o feed RSS na sua página, mas isso só vai funcionar se o usuário copiar e colar manualmente no seu leitor de RSS. Você pode deixar as coisas um pouco mais fáceis ao usar uma tag <link rel=\"alternate\"> no <head> do seu HTML.
Com isso, se o usuário colar o URL de seu blog no leitor RSS, ele poderá obter o link do RSS automaticamente. No Nuxt, isso pode ser feito com o composable useHead.
useHead({\n link: [{ \n rel: 'alternate', \n type: 'application/rss+xml', \n title: 'Feed (RSS)', \n href: '/blog/feed.xml',\n }],\n});\nIsso não é obrigatório, mas é considerado uma boa prática.
\nO feed atual irá funcionar corretamente para todos os usuários, mas nós estamos somente disponibilizando os links: não há conteúdo para as postagens. A maioria dos sites faz somente isso, mas acredito que é uma boa pedida também disponibilizar o conteúdo completo da postagem, assim o usuário pode ler em seu ambiente preferido.
\nEsta é a parte mais difícil de ser feita com Nuxt Content. No momento que escrevo este artigo, o Nuxt Content não parece ter um método que retorna sua postagem renderizada em HTML no contexto do servidor. Precisamos fazer isso manualmente.
\nO Nuxt Content usa o @nuxtjs/mdc por baixo dos panos, que por sua vez usa os projetos remark e o rehype do ecossistema do Unified.
\nSe você der uma olhada na propriedade post.body, pode notar que é uma Árvore Sintática Abstrata (ASA) do Minimark. Poderíamos usar o pacote minimark para obter a string do Markdown, mas eu encontrei alguns problemas de conversão quando tentei. É mais fácil obter o código-fonte do arquivo Markdown diretamente.
Para deixar as coisas reutilizáveis, iremos criar uma função utilitária no servidor chamada markdownToHtml.
import { readFile } from 'node:fs/promises';\nimport { join } from 'node:path';\n\nexport async function markdownToHtml(fileName: string) {\n const filePath = join(process.cwd(), 'content', `${fileName}.md`);\n const markdown = await readFile(filePath, 'utf-8');\n}\nA parte difícil é criar o pipeline da biblioteca Unified de tal modo que ele faça uma conversão similar a que o Nuxt Content faz. Podemos começar importando os plugins.
\nimport rehypeSlug from 'rehype-slug';\nimport rehypeStringify from 'rehype-stringify';\nimport remarkFrontmatter from 'remark-frontmatter';\nimport remarkGfm from 'remark-gfm';\nimport remarkMdc from 'remark-mdc';\nimport remarkParse from 'remark-parse';\nimport remarkRehype from 'remark-rehype';\nimport { unified } from 'unified';\nE então criando o pipeline.
\nconst result = await unified()\n .use(remarkParse)\n .use(remarkFrontmatter, ['yaml'])\n .use(remarkGfm)\n .use(remarkMdc)\n .use(remarkRehype)\n .use(rehypeSlug)\n .use(rehypeStringify)\n .process(markdown);\n\nreturn String(result);\nIsso irá fazer o parse do Markdown, criar uma ASA, que então irá ser convertida para HAST e processada até que seja reduzida a uma string final com o HTML.
\nPara a maioria dos casos, isso irá funcionar, mas o MDC suporta componentes Vue, o que é um problema neste caso. A abordagem que eu escolhi foi converter os componentes que eu uso em componentes simples e equivalentes que usam apenas tags já existentes do HTML.
\nSe você tem algum componente no seu Markdown, o pipeline existente irá colocá-lo no HTML como se ele fosse um elemento personalizado. Por exemplo, o Note.vue, chamado por ::note no Markdown, irá ser transformado em <note></note>, que não é um elemento existente do HTML.
Podemos contornar isso usando o plugin rehype-components. Também iremos precisar instalar o pacote hastscript.
\nO que esse plugin faz é converter elementos personalizados em outros que você especifica. Podemos colocar ele no pipeline com o seguinte código.
\n.use(rehypeComponents, {\n components: {\n 'note': Note,\n },\n})\nE então criamos um componente Note para a substituição. Neste caso, o elemento Note é originalmente um callout. A abordagem que eu escolhi foi transformá-lo numa <div> com <p><strong>Nota:</strong></p> no seu primeiro filho.
O componente Note pode ser definido como:
import { h } from 'hastscript';\nimport type { ComponentFunction } from 'rehype-components';\n\nconst Note: ComponentFunction = (_, children) => h('div', [\n h('p', h('strong', 'Nota:')),\n ...children,\n]);\nNeste exemplo, o seguinte bloco Note no Markdown
::note\nEsta é uma nota\n::\nSerá transformada no seguinte HTML:
\n<div>\n <p><strong>Nota:</strong></p>\n <p>Esta é uma nota</p>\n</div>\nComo você deve ter imaginado, você irá precisar fazer isso para cada componente Vue que você usa nos seus arquivos Markdown.
\nCom a função completada, podemos colocar o resultado em cada item do feed:
\nfeed.item({\n title: post.title,\n guid: `${url}/post/${slug}`,\n url: `${url}/post/${slug}`,\n description: post.description,\n date: new Date(post.created_at),\n categories: post.category ? [post.category] : undefined,\n custom_elements: [\n { 'dc:creator': { _cdata: 'Fulano de Tal' } },\n { 'content:encoded': { _cdata: await markdownToHtml(post.path) } }, // [!CODE ++]\n ],\n});\nAgora o feed RSS está completo com o conteúdo de suas postagens também.
\nUma idéia alternativa que eu tive para resolver este problema foi usar um dos hooks do Nuxt após o build. Você pode escrever um script personalizado que faça o parse do HTML gerado para /blog para pegar os links, e então fazer o parse de cada arquivo de postagem gerado para extrair a parte do texto.
Isso vai funcionar, mas dependendo dos seus elementos personalizados, você pode acabar obtendo um HTML sujo quando comparado ao fazer o parse do Markdown. Por exemplo, alguns dos blocos <pre> que eu uso aqui são customizados para incluir uma janela bonitinha ao redor com o nome do arquivo e também um botão para copiar o código. Se você não tratar esses casos, os leitores RSS podem não renderizar o conteúdo de uma maneira correta.
Seria legal se a equipe do Nuxt disponibilizasse uma maneira mais fácil de fazer isso, já que feeds RSS ainda são bem úteis e usados por algumas pessoas. Talvez com uma reescrita do módulo para usar Comark eles acabem implementando? Quem sabe.
","date_published":"2026-06-17T00:00:00.000Z","date_modified":"2026-06-19T18:36:00.000Z","tags":["Programação"],"language":"pt-BR"},{"id":"chegou-a-hora-de-aposentar-o-notion-como-cms","url":"https://alessandrojean.github.io/post/chegou-a-hora-de-aposentar-o-notion-como-cms","title":"Chegou a hora de aposentar o Notion como CMS","summary":"Notas sobre a migração do CMS do blog de Notion para Nuxt Content.","content_html":"Há quase quatro anos atrás, eu comecei a utilizar o Notion como uma espécie de CMS para este blog pessoal. Durante um tempo, esta abordagem funcionou bem, mas depois comecei a me sentir bastante limitado com os blocos que o Notion oferece para escrever os textos.
\nApesar de facilitar um pouco o fluxo de publicação, a plataforma sempre ofereceu algumas barreiras em como eles entregam seu conteúdo pela API, seja por conta das muitas requisições necessárias para obter uma única página, ou até mesmo pelo prazo de expiração nas imagens enviadas.
\nComo não ando escrevendo mais com tanta frequência, acredito que vale a pena voltar a manter os posts em formato Markdown diretamente no repositório. Isto acaba me oferecendo mais autonomia e também um controle maior da estrutura dos elementos que posso usar durante a escrita.
\nNo aspecto técnico, acabei utilizando o Nuxt Content para fazer o gerenciamento do conteúdo. Converter o que estava no Notion foi relativamente fácil, já que agora eles permitem exportar os documentos em formato Markdown.
\nUma mudança pequena, mas significativa que acabei fazendo na migração, foi remover os embeds de tweets. Já não é de hoje que não me sinto mais confortável em usar o que o Twitter se tornou, então acredito que é justo também não colocar nenhum script deles no meu site. Para o único post (por enquanto) que fazia uso desse tipo de conteúdo, optei por criar uma citação especial, inspirada no estilo do Manual do Usuário.
\n\nAs citações de posts de redes sociais agora são assim, o que também permite maior flexibilidade já que posso citar posts de quaisquer sites.
— Alessandro Jean, Autor deste site
Removi também a seção de comentários de filmes do site. Com meu uso mais frequente do Letterboxd, creio que faz mais sentido postar meus comentários nos reviews por lá.
\nDe coisas futuras a serem feitas, eu ainda quero melhorar um pouco a tipografia.
","date_published":"2026-06-14T00:00:00.000Z","date_modified":"2026-06-16T22:48:00.000Z","tags":["Programação"],"language":"pt-BR"},{"id":"redesign-do-site","url":"https://alessandrojean.github.io/post/redesign-do-site","title":"Redesign do site","summary":"Sobre o redesign do site e a nova sessão de comentários de filmes.","content_html":"Após um período parado, consegui um tempo para fazer um redesign no site.
\nOs posts no blog mantém a mesma estrutura, mas inaugurei uma sessão nova com comentários sobre filmes que assisto (link aqui). Estou longe de ser um crítico especializado em cinema, então esses comentários são descompromissados e apenas casuais, como uma espécie de diário.
\nA página inicial foi simplificada, bem como a listagem dos posts na página do blog. Por baixo dos panos, o site foi totalmente reescrito, mas continua usando o Notion como “banco de dados” e Nuxt como o framework gerador.
\nProvavelmente ainda devem ter alguns bugs e problemas aqui e ali, mas espero resolvê-los com o passar do tempo.
","date_published":"2025-10-03T00:00:00.000Z","date_modified":"2025-10-03T00:00:00.000Z","tags":["Cotidiano"],"language":"pt-BR"},{"id":"interagindo-com-bibliotecas-em-c-usando-codigo-em-haskell","url":"https://alessandrojean.github.io/post/interagindo-com-bibliotecas-em-c-usando-codigo-em-haskell","title":"Interagindo com bibliotecas em C usando código em Haskell","summary":"Uma breve introdução ao recurso de interoperabilidade da linguagem Haskell, mostrando a conversão entre os tipos das linguagens por meio de exemplos com as bibliotecas em C do FFmpeg e do VLC.","content_html":"Uma necessidade comum em algumas aplicações específicas é poder utilizar alguma biblioteca nativa do sistema operacional diretamente, mesmo não utilizando a linguagem que ela foi escrita (normalmente C ou C++). A maioria das linguagens de programação modernas permitem que tais funções sejam utilizadas através do recurso de interoperabilidade.
\nO objetivo deste tutorial é demonstrar como a interoperabilidade funciona no Haskell no sentido de utilizar bibliotecas existentes em C, bem como a conversão entre os tipos de ambas as linguagens. Para tal, serão mostrados alguns exemplos onde serão criadas algumas bibliotecas próprias, e outros onde serão alguns exemplos mais objetivos através da utilização do FFmpeg e VLC.
\nO código final deste artigo está disponível no GitHub no repositório alessandrojean/haskell-c-interop.
\nNota:
Este tutorial foi escrito como um dos projetos da disciplina Desenvolvimento Guiado a Tipos do Bacharelado em Ciência da Computação na UFABC em Abril de 2024.
math.h diretamente\n\nInteroperabilidade é a capacidade de duas linguagens de programação diferentes interagirem de maneira nativa como parte de um mesmo sistema e operar com os mesmos tipos de estruturas de dados.
\n— Wikipédia (em inglês)\n
O Haskell oferece a interoperabilidade através do método de interfaces de funções externas (FFI), o que permite que nosso código em Haskell possa chamar funções escritas em C ou C++. Essas interfaces permitem que sejam construídas bibliotecas em Haskell que ofereçam funcionalidades de bibliotecas em C, facilitando o acesso e inclusive permitindo um estilo que seja mais idiomático para o Haskell, com (mas não limitado somente) a conversão para o paradigma funcional (Wikipédia). Tais bibliotecas são comumente conhecidas como wrappers ou bindings.
\nSimilar ao tutorial anterior, iremos utilizar o Haskell Stack para a criação do projeto. Todo o pacote de desenvolvimento foi instalado através do GHCup. Para iniciar a pasta do projeto, utilizamos o comando:
\n$ stack new c-interop simple\nApós as dependências e o template terem sido baixados, podemos abrir a pasta em um editor de código com suporte a Haskell e C/C++, como o Visual Studio Code.
\nComeçando com um exemplo simples, utilizaremos uma biblioteca própria que só vai ter uma função. Para este exemplo, vamos criar uma biblioteca de matemática que irá exportar a função exponencial (e ^ x) definida como my_exp.
Primeiramente, precisaremos criar o arquivo de cabeçalho que irá definir todas as funções que nossa biblioteca exportará para o uso de outros programas.
\n#ifndef MY_MATH_H\n#define MY_MATH_H\n\nextern double my_exp(double);\n\n#endif // my_math\nA diferença significativa deste código para o que é comumente utilizado em arquivos de cabeçalho em C é a utilização da palavra-chave extern antes da definição da função. Ela que irá indicar quais funções ficarão acessíveis por outros programas.
Com o cabeçalho pronto, podemos implementar a nossa função em um arquivo separado.
\n#include <math.h>\n#include \"my_math.h\"\n\n#define EULER_NUM 2.71828\n\ndouble my_exp(double number) {\n return pow(EULER_NUM, number);\n}\nEste código não tem muito segredo: utilizamos a biblioteca libmath do C para usar somente a função pow, permitindo que façamos a operação e ^ number. Poderíamos implementá-la manualmente, mas para fins de simplificação do código, é mais rápido utilizar a função oficial.
Para poder compilar a biblioteca, utilizaremos um fluxo em duas etapas: primeiro criaremos o objeto (my_math.o) para aí sim poder criar a biblioteca (libmy_math.so).
Para criar o objeto, utilizaremos o gcc do mesmo modo que seria utilizado para compilar um arquivo simples qualquer. A diferença, é que utilizaremos a flag -fpic, ideal para o uso em bibliotecas, pois evita alguns possíveis conflitos com outras bibliotecas.
$ gcc -c -Wall -Werror -fpic my_math.c\nO comando irá produzir um arquivo my_math.o, que será utilizado em sequência no gcc para criar a biblioteca com o comando a seguir.
$ gcc -shared -o ../libs/libmy_math.so my_math.o\nCom isso, temos a biblioteca compilada, podemos utilizá-la no nosso código em Haskell.
\nPara poder compilar o projeto com o stack, é necessário adicionar algumas flags ao compilador do Haskell, o ghc. No arquivo c-interop.cabal na raiz do projeto, é necessário incluir as seguintes linhas na propriedade ghc-options:
ghc-options: -- Demais flags omitidas.\n -- Define um diretório extra para as bibliotecas. -- [!code ++]\n -L./libs -- [!code ++]\n -- Define um diretório extra para os cabeçalhos. -- [!code ++]\n -I./my_math -- [!code ++]\n -- Utiliza a biblioteca my_math na compilação. -- [!code ++]\n -lmy_math -- [!code ++]\nTemos este pequeno trabalho a ser feito por conta dos arquivos não estarem em diretórios comuns do sistema operacional, mas veremos no próximos exemplo que não será necessário especificar estes diretórios ao utilizar dependências instaladas globalmente de maneira direta.
\nAgora finalmente poderemos modificar o código em Haskell. Primeiramente, é necessário usar duas diretivas de linguagem para habilitar a chamada de funções externas, bem como importar os tipos primitivos do C.
\n{-# LANGUAGE ForeignFunctionInterface, CApiFFI #-}\nmodule Main (main) where\n\nimport Foreign.C.Types\nOs tipos primitivos nos possibilitarão uma melhor definição das funções externas até por conta das diferenças de tamanho entre os tipos do Haskell e do C, que também podem ter diferenças entre os processadores e sistemas operacionais. Tendo feito as importações, podemos definir no arquivo o acesso a função my_exp da nossa biblioteca utilizando o código a seguir.
foreign import capi \"my_math.h my_exp\" c_myExp :: CDouble -> CDouble\nEssa importação é especial, pois explicita que a função irá vir de uma dependência externa, bem como define que será feito uma chamada a uma função em C, especificada juntamente ao cabeçalho da função. Como o compilador do Haskell não consegue prever a tipagem da função, é necessário deixar a tipagem explícita.
\nPode-se utilizar tanto a palavra-chave capi quando ccall, com a diferença que ao utilizar capi, os tipos serão checados com o compilador do C na hora de fazer o link entre as duas linguagens. Para um ambiente mais seguro em relação a tipos, torna-se interessante utilizar o capi, que inclusive é o recomendado pela documentação do Haskell atualmente.
É uma convenção do Haskell utilizar o prefixo c_ para indicar funções e/ou constantes que sejam de bibliotecas externas em C, por isso ela é nomeada assim. Após a importação, podemos utilizá-la como uma função qualquer em Haskell, com a diferença que será necessário lidar com alguns tipos especiais, como o CString e Ptr ao utilizá-los.
main :: IO ()\nmain = do\n print $ c_myExp 5\nPara compilar utilizaremos o stack novamente, mas com algumas diferenças.
$ stack build\nApós a compilação ter sido concluída, podemos executar o arquivo.
\n$ LD_LIBRARY_PATH=./libs stack exec c-interop\n148.41265995084171\nAqui tem uma diferença no comando: é necessário especificar o local das bibliotecas externas nesse caso por conta de não ser o comum do sistema operacional. Como as bibliotecas são carregadas em tempo de execução, o programa precisa saber novamente onde as encontrar.
\nAo executar, obtemos o resultado correto de 148.41265995084171 impresso na tela.
math.h diretamenteNa seção anterior, criamos uma biblioteca nossa e chamamos a função no código em Haskell. Nesta, iremos utilizar uma biblioteca da linguagem C que já está disponível globalmente no sistema operacional, onde teremos diferenças e simplificações na hora de compilação e execução.
\nA principal diferença é que não precisaremos modificar as flags de compilação do ghc no arquivo c-interop.cabal para incluir os diretórios dos cabeçalhos e da nossa biblioteca, mas sim apenas será necessário a utilização da libmath do próprio C. As linhas podem ser comentadas ou removidas neste caso, pois não serão mais utilizadas.
ghc-options: -- Demais flags omitidas.\n -L./libs -- [!code --]\n -I./my_math -- [!code --]\n -lmy_math -- [!code --]\n -lmath -- [!code ++]\nDe maneira similar, iremos importar a função exp da biblioteca math.h no código Haskell.
foreign import capi \"math.h exp\" c_exp :: CDouble -> CDouble\n\nmain :: IO ()\nmain = do\n print $ c_exp 5\nPara compilar e executar, basta usarmos os comandos padrões do stack:
$ stack build\n$ stack exec c-interop\n148.4131591025766\nVeja como não é necessário também definir a variável de ambiente LD_LIBRARY_PATH na hora de execução, visto que o programa sabe onde encontrar a biblioteca libmath.so na pasta padrão do sistema operacional, pois é uma biblioteca instalada globalmente.
Nesta seção, utilizaremos a API do FFmpeg para criar um programa simples que imprime os metadados de um arquivo suportado pela ferramenta.
\nO FFmpeg é uma ferramenta de código aberto vastamente utilizada por diversos sistemas de multimídia, programado em C e Assembly para uma melhor performance. Ela permite a conversão entre formatos (ffmpeg), visualização de metadados (ffprobe) e reprodução de arquivos (ffplay). Todos os grandes players no mercado como YouTube e Netflix utilizam-o em algum dado momento nos seus fluxos.
![\"Quadrinho](\"https://alessandrojean.github.io/posts/2024/2024-05-08-interagindo-com-bibliotecas-em-c-usando-codigo-em-haskell/xkcd.jpeg\")
O intuito deste exemplo é construir uma espécie simplificada da ferramenta ffprobe disponível pelo FFMpeg. O ffprobe é um utilitário que exibe informações de um arquivo passado pela linha de comando. Ao usar em um arquivo de exemplo, podemos observar a saída abaixo.
$ ffprobe big_buck_bunny.mp4\nffprobe version 6.0-6ubuntu1 Copyright (c) 2007-2023 the FFmpeg developers\nInput #0, mov,mp4,m4a,3gp,3g2,mj2, from '/home/alessandro/Downloads/bbb_sunflower_1080p_30fps_normal.mp4':\n Metadata:\n major_brand : isom\n minor_version : 1\n compatible_brands: isomavc1\n creation_time : 2013-12-16T17:44:39.000000Z\n title : Big Buck Bunny, Sunflower version\n artist : Blender Foundation 2008, Janus Bager Kristensen 2013\n comment : Creative Commons Attribution 3.0 - http://bbb3d.renderfarming.net\n genre : Animation\n composer : Sacha Goedegebure\n Duration: 00:10:34.60, start: 0.000000, bitrate: 3481 kb/s\n Stream #0:0[0x1](und): Video: h264 (High) (avc1 / 0x31637661), yuv420p(progressive), 1920x1080 [SAR 1:1 DAR 16:9], 2998 kb/s, 30 fps, 30 tbr, 30k tbn (default)\n Metadata:\n creation_time : 2013-12-16T17:44:39.000000Z\n handler_name : GPAC ISO Video Handler\n vendor_id : [0][0][0][0]\n Stream #0:1[0x2](und): Audio: mp3 (mp4a / 0x6134706D), 48000 Hz, stereo, fltp, 160 kb/s (default)\n Metadata:\n creation_time : 2013-12-16T17:44:42.000000Z\n handler_name : GPAC ISO Audio Handler\n vendor_id : [0][0][0][0]\n Stream #0:2[0x3](und): Audio: ac3 (ac-3 / 0x332D6361), 48000 Hz, 5.1(side), fltp, 320 kb/s (default)\n Metadata:\n creation_time : 2013-12-16T17:44:42.000000Z\n handler_name : GPAC ISO Audio Handler\n vendor_id : [0][0][0][0]\n Side data:\n audio service type: main\nPara utilizar a API do FFmpeg, iremos precisar da libavformat e libavutil instaladas. Também iremos utilizar a libavcodec, mas ela já vem inclusa na instalação de ambas as bibliotecas, que estão disponíveis nos repositórios das distribuições Linux. Como exemplo do Ubuntu, elas estão disponíveis no apt e podem ser instaladas utilizando o comando abaixo.
$ sudo apt install libavformat-dev libavutil-dev\nUtilizamos as variantes com o sufixo -dev pois queremos que os arquivos de cabeçalho também sejam baixados e disponibilizados para serem usados em programas que vamos escrever.
O código deste exemplo é baseado em um exemplo oficial do FFmpeg que pode ser visto na íntegra neste link no repositório do GitHub do projeto. No código, o arquivo passado como primeiro argumento na linha de comando é aberto como um input, onde seus metadados são processados, iterados, e exibidos na tela.
\nPara poder replicar este código em Haskell, criaremos uma interface escrita em C para intermediar (e facilitar) a comunicação entre nosso programa em Haskell e a biblioteca do FFmpeg. Esse programa intermediador irá expor duas funções para ler as informações do arquivo e uma struct especial com menos campos para facilitar a declaração dos tipos no Haskell.
De maneira similar ao exemplo anterior, iremos criar um arquivo de cabeçalho ffmpeg.h.
#ifndef FFMPEG_H\n#define FFMPEG_H\n\n#include <libavformat/avformat.h>\n#include <libavutil/dict.h>\n\nstruct FfmpegInput {\n AVDictionary * metadata;\n AVDictionary * format_metadata;\n AVDictionary ** streams_metadata;\n int nb_streams;\n AVFormatContext * context;\n};\n\ntypedef struct FfmpegInput FfmpegInput;\n\nextern FfmpegInput * load_input(const char *);\nextern void free_input(FfmpegInput *);\n\n#endif // ffmpeg_h\nExplicando resumidamente, a struct FfmpegInput irá guardar três informações: um dicionário com os metadados do arquivo (metadata), um segundo dicionário com os metadados do formato do arquivo (format_metadata) e o contexto original da biblioteca, que será utilizado apenas para liberar a memória no final do uso do programa e não será acessado no código em Haskell.
Partindo para a implementação da primeira função, iremos utilizar uma abordagem similar a do exemplo no repositório do FFmpeg.
\n#include <stdio.h>\n#include <libavformat/avformat.h>\n#include <libavutil/dict.h>\n#include <libavcodec/codec.h>\n#include <libavcodec/codec_desc.h>\n#include \"ffmpeg.h\"\n\nFfmpegInput * load_input(const char * file_name) {\n AVFormatContext * format_context = NULL;\n\n // Tenta abrir o arquivo, retorna um inteiro > 0 se deu algum erro.\n if (avformat_open_input(&format_context, file_name, NULL, NULL)) {\n return NULL;\n }\n\n // Tenta ver se há alguma trilha de vídeo e/ou áudio no arquivo.\n // Retorna valores negativos se deu algum erro.\n if (avformat_find_stream_info(format_context, NULL) < 0) {\n av_log(NULL, AV_LOG_ERROR, \"Cannot find stream information\\n\");\n return NULL;\n }\n\n FfmpegInput * input = malloc(sizeof (FfmpegInput));\n\n if (input == NULL) {\n fprintf(stderr, \"Failed to allocate necessary bytes for input\\n\");\n return NULL;\n }\n\n // Cria um dicionário que irá ter alguns metadados do arquivo.\n AVDictionary * metadata = NULL;\n av_dict_copy(&metadata, format_context->metadata, AV_DICT_DONT_OVERWRITE);\n create_file_dict(&metadata, format_context); \n\n // Cria um dicionário que irá ter alguns metadados do formato.\n AVDictionary * format_metadata = NULL;\n create_format_dict(&format_metadata, format_context->iformat);\n\n // Cria um vetor de dicionários que irão ter alguns metadados das streams.\n AVDictionary ** streams_metadata = calloc(format_context->nb_streams, sizeof(AVDictionary *));\n create_streams_dict(streams_metadata, format_context);\n\n input->context = format_context;\n input->metadata = metadata;\n input->format_metadata = format_metadata;\n input->nb_streams = format_context->nb_streams;\n input->streams_metadata = streams_metadata; \n\n return input;\n}\nComo explicado anteriormente, o código é baseado num exemplo oficial. A maior diferença é que estamos obtendo algumas informações da biblioteca e passando-as para um tipo de nosso domínio que é bem mais simplificado. Isso é feito porque os tipos da biblioteca do FFmpeg possuem macros e condicionais nas declarações, tornando a declaração no Haskell mais complexa e necessitando de ferramentas externas no fluxo de compilação.
\nA função create_format_dict chamada no meio do código é apenas uma função auxiliar que preenche o dicionário com alguns atributos básicos do formato.
void create_format_dict(AVDictionary ** dict, const AVInputFormat * iformat) {\n av_dict_set(dict, \"name\", iformat->name, AV_DICT_DONT_OVERWRITE);\n av_dict_set(dict, \"long_name\", iformat->long_name, AV_DICT_DONT_OVERWRITE);\n av_dict_set(dict, \"extensions\", iformat->extensions, AV_DICT_DONT_OVERWRITE);\n av_dict_set(dict, \"mime_type\", iformat->mime_type, AV_DICT_DONT_OVERWRITE);\n}\nDe modo similar, as funções create_streams_dict e create_file_dict criam dicionários que conterão metadados das streams e do arquivo, respectivamente. O código delas foi omitido por simplificação, mas está disponível no repositório no GitHub do tutorial.
Não é necessário alocar a memória para o tipo AvDictionary explicitamente, pois o FFmpeg já faz isso por padrão na primeira chamada da função av_dict_set, segundo a documentação.
\n\n\n
pm— Pointer to a pointer to a dictionary struct. If*pmisNULLa dictionary struct is allocated and put in*pm.
A função de liberação de memória é bem simples e concisa.
\nvoid free_input(FfmpegInput * input) {\n avformat_free_context(input->context);\n av_dict_free(&input->format_metadata);\n av_dict_free(&input->metadata);\n\n for (int i = 0; i < input->nb_streams; i++) {\n av_dict_free(&input->streams_metadata[i]);\n }\n\n free(input);\n}\nAqui são utilizados duas funções específicas do FFmpeg para a liberação da memória tanto do contexto quanto do dicionário. A biblioteca lida com todos os campos internos de ambas as structs. Por fim, é necessário liberar o espaço de memória da nossa struct também.
\nIdêntico ao primeiro exemplo, vamos criar uma biblioteca libffmpeg.so para ser acessada no nosso código em Haskell.
$ gcc -c -Wall -Werror -fpic -lavformat -lavutil -lavcodec ffmpeg.c\n$ gcc -shared -o ../libs/libffmpeg.so ffmpeg.o\nTambém é necessário incluir a biblioteca nas flags do GHC.
\nghc-options: -- Demais flags omitidas\n -L./libs -- [!code ++]\n -I./ffmpeg -- [!code ++]\n -lffmpeg -- [!code ++]\n -lavutil -- [!code ++]\n -lavformat -- [!code ++]\n -lavcodec -- [!code ++]\nPara este segundo exemplo precisaremos usar duas bibliotecas externas disponíveis no Hackage. Para definir a dependência, precisamos primeiramente informar ao stack sobre elas, editando o arquivo de metadados do stack do nosso projeto.
extra-deps:\n - c-storable-deriving-0.1.3 # [!code ++]\n - pretty-terminal-0.1.0.0 # [!code ++]\nTendo informado ao stack, podemos declarar a dependência ao cabal também.
build-depends: base >= 4.7 && < 5,\n containers, -- [!code ++]\n c-storable-deriving, -- [!code ++]\n pretty-terminal -- [!code ++]\nA biblioteca c-storable-deriving nos ajudará a criar a conversão dos tipos do C e Haskell mais facilmente no código final, enquanto a pretty-terminal irá ajudar a deixar a saída no terminal mais elegante com algumas cores. O containers por sua vez é declarado por conta do tipo Map, que será utilizado para acessar os dicionários do FFmpeg mais facilmente após uma conversão.
FFmpeg no HaskellNeste módulo iremos utilizar quatro diretivas de linguagem. Além das já utilizadas anteriormente ForeignFunctionInterface e CApiFFI, precisaremos de duas relacionadas a Generics: DeriveGeneric e DeriveAnyClass.
{-# LANGUAGE ForeignFunctionInterface, CApiFFI #-}\n{-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}\nmodule FFmpeg where\n\nimport Control.Monad (forM_, join)\nimport Data.Maybe\nimport Foreign\nimport Foreign.C.Types\nimport Foreign.C (CString, withCString, peekCString)\nimport Foreign.CStorable (CStorable(..))\nimport GHC.Generics\nimport Data.Map (Map)\nimport qualified Data.Map as Map\n\nimport PrettyPrint\nIremos começar replicando os tipos próprios do FFmpeg, mais especificamente os dicionários.
\nO tipo AVDictionary de libavutil/dict.h é uma struct vazia, como pode-se observar no código da biblioteca no trecho abaixo.
typedef struct AVDictionary AVDictionary;\nComo a struct não tem campos, podemos representá-la no Haskell como um ponteiro para void no C (void *). Tal representação é feita usando o tipo Ptr (), que vem da biblioteca Foreign.
type AvDictionary = Ptr ()\nO tipo AVDictionaryEntry de libavutil/dict.h por sua vez, é uma struct simples com apenas dois campos: key e value, ambos do tipo char *. Por possuir dois campos, podemos representar esta struct com um record semelhante.
data AvDictionaryEntry = AvDictionaryEntry\n { avDictKey :: CString\n , avDictValue :: CString\n }\nPara poder fazer a conversão entre as linguagens, as estruturas de dados precisarão providenciar uma instância da classe Storable. Essa instância pode ser implementada explicitamente, mas para poder implementar, é necessário ter conhecimento nos tamanhos dos tipos e de seus paddings, caso existam, nas estruturas do C, que podem ser consultados na tabela abaixo.
| Tipo | \nArquitetura | \nTamanho (byte) | \nPadding (byte) | \nTotal (byte) | \n
|---|---|---|---|---|
char | \n- | \n1 | \n3 | \n4 | \n
int | \n- | \n16 | \n0 | \n16 | \n
long | \n- | \n32 | \n0 | \n32 | \n
float | \n- | \n4 | \n0 | \n4 | \n
double | \n- | \n8 | \n0 | \n8 | \n
void * | \n32 bits | \n4 | \n0 | \n4 | \n
void * | \n64 bits | \n8 | \n0 | \n8 | \n
Simplificando bastante e considerando uma arquitetura de 32 bits, o padding é usado em estruturas no C para alinhar seus membros internos aos limites de endereço naturais, ou seja, fazendo com que os endereços na memória de cada membro seja um múltiplo de 4. O padding é adicionado por padrão pelo compilador do C, mas pode ser desativado.
\nDica:
Esta pergunta no StackOverflow possui algumas explicações interessantes sobre como o padding e packing funcionam na linguagem C.
Tendo essas informações em mente, podemos implementar nossa própria instância de Storable para nosso tipo AvDictionaryEntry.
instance Storable AvDictionaryEntry where\n alignment _ = 8\n sizeOf _ = 16\n peek ptr = AvDictionaryEntry\n <$> peekByteOff ptr 0\n <*> peekByteOff ptr 8\n poke ptr (AvDictionaryEntry k v) = do\n pokeByteOff ptr 0 k\n pokeByteOff ptr 8 v\nExplicando detalhadamente cada uma das funções de Storable, temos:
alignment deve retornar o alinhamento da estrutura. É representado como o mínimo múltiplo comum entre todos os alinhamentos de seus tipos internos. Como na arquitetura 64 bits temos que um ponteiro representa 8 bytes, e o nosso tipo contém duas variáveis do tipo ponteiro, temos mmc(8, 8) = 8.sizeOf deve retornar o tamanho total em bytes ocupado pela estrutura. Como temos dois ponteiros, temos o total de 16 bytes.peek é a função que fará a leitura dos dados do ponteiro ptr e irá criar a instância do tipo do Haskell. Para tal feito, podemos utilizar a função peekByteOff, onde também é necessário informar o offset inicial da leitura. Esse offset é calculado usando o tamanho do tipo anterior na estrutura e seu possível padding (como acontece em variáveis do tipo char).poke é a função que irá escrever os dados no endereço de memória armazenado no ponteiro. De maneira similar ao peek, usamos a função pokeByteOff também passando o offset e seguindo a ordem da declaração do tipo.Apesar da implementação de Storable para nosso tipo ser relativamente fácil e direta, ainda assim ela requer do programador um conhecimento prévio nos tipos do C para saber seus tamanhos, e ainda apresenta algumas dificuldades específicas como ter que lidar com o tamanho dos ponteiros caso esteja usando uma arquitetura diferente. Para evitar possíveis implementações erradas caso algum cálculo esteja incorreto, podemos utilizar a biblioteca c-storable-deriving.
Para utilizar tal biblioteca, faremos com que o nosso tipo derive os tipos Generic e CStorable.
data AvDictionaryEntry = AvDictionaryEntry\n { avDictKey :: CString\n , avDictValue :: CString\n } -- [!code --]\n } deriving (Generic, CStorable) -- [!code ++]\nÉ necessário que nosso tipo seja totalmente compatível com CStorable, ou seja, os tipos internos precisam ter uma implementação de Storable também, por isso utilizamos os tipos do C CString no lugar de String do Haskell. Agora, podemos simplificar a implementação de Storable usando funções da biblioteca.
instance Storable AvDictionaryEntry where\n alignment _ = 8 -- [!code --]\n alignment = cAlignment -- [!code ++]\n sizeOf _ = 16 -- [!code --]\n sizeOf = cSizeOf -- [!code ++]\n peek ptr = AvDictionaryEntry -- [!code --]\n <$> peekByteOff ptr 0 -- [!code --]\n <*> peekByteOff ptr 8 -- [!code --]\n peek = cPeek -- [!code ++]\n poke ptr (AvDictionaryEntry k v) = do -- [!code --]\n pokeByteOff ptr 0 k -- [!code --]\n pokeByteOff ptr 8 v -- [!code --]\n poke = cPoke -- [!code ++]\nAs funções funcionam da exata mesma maneira da nossa implementação explicita anterior, mas será criada automaticamente em tempo de compilação, além de prevenir erros de cálculo e não mais depender do tamanho dos tipos do C.
\nNota:
A documentação da biblioteca pode ser encontrada no Hackage.
De modo similar, podemos agora definir o tipo que representará a struct FfmpegInput, já usando a implementação com a biblioteca c-storable-deriving.
data FfmpegInput = FfmpegInput\n { ffMetadata :: AvDictionary\n , ffFormat :: AvDictionary\n , ffStreamsMetadata :: Ptr AvDictionary\n , ffStreamsNb :: CInt\n , ffContext :: Ptr ()\n } deriving (Generic, CStorable)\n\ninstance Storable FfmpegInput where\n peek = cPeek\n poke = cPoke\n alignment = cAlignment\n sizeOf = cSizeOf\nNo nosso código em Haskell utilizaremos as duas funções expostas pela nossa biblioteca intermediária, bem como a av_dict_get para poder ler os valores nos dicionários.
foreign import capi \"ffmpeg.h load_input\"\n c_loadInput :: CString -> IO (Ptr FfmpegInput)\n\nforeign import capi \"ffmpeg.h &free_input\"\n c_freeInput :: FunPtr (Ptr FfmpegInput -> IO ())\n\nforeign import capi \"libavutil/dict.h av_dict_get\"\n c_avDictGet :: AvDictionary -> CString -> Ptr AvDictionaryEntry -> CInt -> IO (Ptr AvDictionaryEntry)\n\nforeign import capi \"libavutil/dict.h value AV_DICT_IGNORE_SUFFIX\"\n c_avDictIgnoreSuffix :: CInt\nNote que na declaração de tipos sempre utilizamos os tipos do C que vem de Foreign.C.Types para representar a diferença com os tipos do Haskell. Também são utilizados ponteiros para representar as funções exatamente como são declaradas no C.
Aqui cabe uma atenção especial a função c_freeInput. Ela é importada e declarada de uma maneira diferente das outras porque será utilizada em conjunto posteriormente com o tipo ForeignPtr. O Haskell é conhecido por ter um ótimo compilador e fazer um bom uso da memória, entretanto se tratando de ponteiros externos, a linguagem não tem como saber quando é necessário liberar a memória dessas estruturas, cabendo a nós liberarmos a memória manualmente. Porém, o Haskell nos disponibiliza o ForeignPtr justamente para essas situações: são ponteiros especiais que já liberam a memória automaticamente quando não há mais nenhum uso da variável, similar ao que acontece com classes que implementam o Closeable no Java.
A última importação, por sua vez, utiliza o modificador especial value, que permite que sejam importados valores no lugar de funções, sejam esses uma variável ou até mesmo uma constante definida com um macro #define no compilador do C.
Para evitar ter que usar as funções importadas do C diretamente, podemos criar algumas funções auxiliares para evitar ter que ficar usando ponteiros de tipos primitivos nos outros módulos.
\nA primeira função que iremos criar é a loadInput, que será um wrapper ao redor de c_loadInput do C.
loadInput :: String -> IO (Maybe (ForeignPtr FfmpegInput))\nloadInput file = do\n inputPtr <- withCString file $ \\c_file -> c_loadInput c_file\n foreignPtr <- newForeignPtr c_freeInput inputPtr\n return $ if inputPtr == nullPtr then Nothing else Just foreignPtr\nObserve que a partir de agora praticamente todas as operações estarão dentro do escopo de IO, visto que a maioria das funções de leitura e escrita de ponteiros opera neste escopo.
Como a função c_loadInput depende de uma CString, é necessário alocar uma. A biblioteca Foreign oferece uma função auxiliar chamada withCString que permite alocar uma CString temporária que será liberada da memória no fim de seu uso. Usando-a, podemos chamar a c_loadInput com o file convertido de [Char] do Haskell para CString.
Tendo um ponteiro comum, transformamos-o em um ForeignPtr, informando que a função c_freeInput que será usada quando a memória poder ser liberada. No fim, verificamos se a chamada retornou um ponteiro não-nulo, e se for o caso podemos tirar vantagem do Maybe para evitar ter que ficar fazendo comparações diretas com nullPtr, o equivalente do NULL do C.
A segunda função auxiliar que iremos criar é um wrapper ao redor de c_avDictGet.
dictGet :: AvDictionary -> Ptr AvDictionaryEntry -> IO (Ptr AvDictionaryEntry)\ndictGet dict previous = withCString \"\" $ \\c_str ->\n c_avDictGet dict c_str previous avDictIgnoreSuffix\nDe maneira similar a loadInput, utilizamos novamente a withCString.
A última função auxiliar faltando é a de conversão do tipo AvDictionary para um Map String String do Haskell, que permitirá um uso mais fácil dessa estrutura de dados. Essa função, chamada de dictToMap, será dividida em duas: a função simples e a recursiva. A simples será a “porta de entrada” que começará a recursividade.
No exemplo oficial do FFmpeg, para poder ler um AVDictionary, é necessário usar um while.
const AVDictionaryEntry * tag = NULL;\n\nwhile ((tag = av_dict_get(fmt_ctx->metadata, \"\", tag, AV_DICT_IGNORE_SUFFIX))) {\n printf(\"%s=%s\\n\", tag->key, tag->value);\n}\nPara simular este comportamento e iterar sobre todos os itens do dicionário no Haskell, será necessário usar o paradigma funcional e, portanto, utilizar recursão.
\ndictToMap' :: AvDictionary -> Map String String -> Ptr AvDictionaryEntry -> IO (Map String String)\ndictToMap' dict mp tagPtr | tagPtr == nullPtr = pure mp\n | otherwise = nextCall\n where\n key = peek tagPtr >>= \\t -> peekCString $ avDictKey t\n value = peek tagPtr >>= \\t -> peekCString $ avDictValue t\n newMap = liftA2 (\\k v -> Map.insert k v mp) key value\n nextTag = dictGet dict tagPtr\n nextCall = join $ liftA2 (dictToMap' dict) newMap nextTag\nA ideia dessa função é ir iterando sobre todas as entradas no dicionário, adicionando-as num mapa até chegar na última entrada. Similar ao while, temos como condição de parada da recursão o ponteiro para a próxima entrada ser nulo, então é necessário comparar tagPtr com nullPtr.
Aqui começamos o uso das funções de leituras de ponteiros, utilizamos peek para poder ler o valor de tagPtr, que nos colocará no contexto de IO. Também é necessário, em seguida, utilizar a peekCString para ler o valor da CString tanto de key quando de value. No final, teremos ambos como IO String.
Como ambas as strings estão no contexto IO, precisamos chamar a função Map.insert dentro deste contexto. Para isso, podemos usar a função liftA2 que permite fazer o unbox de duas variáveis no mesmo contexto, aplicar uma função com os valores internos e então retornar ao contexto anterior. No final, teremos um IO (Map String String). Por baixo dos panos, a função liftA2 está fazendo a mesma coisa do código abaixo.
newMap = do\n k <- key\n v <- value\n return $ Map.insert k v\nAgora podemos fazer a próxima chamada recursiva, mas como temos ambos o newMap e nextTag no contexto IO, precisamos usar o join em conjunto com o liftA2 para poder acessar os valores de ambas para aí sim poder chamar a própria função novamente. O join neste caso irá extrair uma “camada” do IO do tipo, transformando um IO (IO ()) em IO (), por exemplo.
Com a recursividade pronta, podemos criar a função simples de entrada.
\ndictToMap :: AvDictionary -> IO (Map String String)\ndictToMap dict = do\n firstTag <- dictGet dict nullPtr\n dictToMap' dict Map.empty firstTag\nNesta função, precisamos obter a primeira entrada para iniciar a recursividade corretamente, caso contrário, estaríamos passando um nullPtr diretamente e a recursão nem iria começar. Agora com esta função, podemos converter um AvDictionary para Map String String, permitindo um acesso mais fácil no nosso código Haskell.
A última função que iremos criar neste módulo é a responsável por enfim imprimir os metadados. Ela será chamada no módulo Main posteriormente. Para deixar a saída no terminal um pouco mais bonita, duas funções são usadas: prettyTitle e prettyTitle. O código dessas duas funções se encontra no módulo PrettyPrint e está disponível no repositório do GitHub deste tutorial. Para fins de simplificação, optei por não incluir a implementação aqui, mas o importante de saber sobre elas é que, como o nome sugere, uma irá imprimir um título de modo “bonito” e o outro imprimirá todas as entradas do Map String String de modo “bonito” também.
A lógica dessa função segue o seguinte algoritmo:
\nprintMetadata :: String -> IO ()\nprintMetadata fileName = do\n inputPtr' <- loadInput fileName\n let inputForeignPtr = fromJust inputPtr'\n\n withForeignPtr inputForeignPtr $ \\inputPtr -> do\n input <- peek inputPtr \n metadata <- dictToMap $ ffMetadata input\n formatMetadata <- dictToMap $ ffFormat input\n\n let nbStreams = fromIntegral . toInteger $ ffStreamsNb input\n streamsMetadataPtr = ffStreamsMetadata input\n\n streamsMetadata <- peekArray nbStreams streamsMetadataPtr\n\n prettyTitle \"File metadata\"\n prettyPrint metadata\n putStrLn \"\"\n\n prettyTitle \"Format metadata\"\n prettyPrint formatMetadata\n putStrLn \"\"\n\n forM_ (zip [0..nbStreams-1] streamsMetadata) $ \\(i, sMetadataPtr) -> do\n sMetadata <- dictToMap sMetadataPtr\n\n prettyTitle $ \"Stream #\" ++ show i\n prettyPrint sMetadata\n putStrLn \"\"\nPara fazer aproveitar da vantagem do ForeignPtr, utilizamos a função withForeignPtr, que nos permite ter acesso a um ponteiro Ptr comum, o qual podemos acessar e/ou modificar seus conteúdos. Toda a lógica que acessa os dados do nosso tipo FFmpegInput é feita dentro dessa função anônima que é passada para a função.
Para iterar no vetor de ponteiros que representa o vetor dos dicionários das streams, precisamos primeiramente converter o tipo Ptr [AvDictionary] (que é igual a Ptr [Ptr ()]) para uma lista do Haskell, para poder iterar posteriormente, obtendo um [AvDictionary]. Tendo esta lista de ponteiros, podemos iterar usando o forM_, assim imprimindo os metadados de cada stream.
Por conta das funções auxiliares no módulo FFmpeg, nosso código ficou muito mais legível e fácil de entender mesmo para quem não tem tanta familiaridade com as minúcias do C.
Com o módulo FFmpeg pronto, podemos finalmente editar o nosso arquivo Main.hs. Iremos ler o caminho do arquivo da linha do comando do usuário.
module Main (main) where\n\nimport System.Environment\nimport FFmpeg\nimport Vlc\n\nmain :: IO ()\nmain = do\n args <- getArgs\n\n let fileName = head args\n printMetadata fileName\nA implementação é bem direta ao ponto, obtemos os argumentos da linha de comando assumindo que o primeiro deles é um caminho válido para um arquivo existente. Tendo este caminho, basta utilizá-lo na chamada da função printMetadata. Note que por conta das funções auxiliares do módulo FFmpeg, não precisamos interagir com nada relacionado a linguagem C no módulo Main.
Com nosso código pronto, podemos compilar e executar de maneira similar ao primeiro exemplo.
\n$ stack build\n$ LD_LIBRARY_PATH=./libs stack exec c-interop big_buck_bunny.mp4\nAo observar a saída, vemos que o texto no terminal está colorido e também está seguindo a sintaxe de arquivos .ini, como pode-se observar abaixo na íntegra. O arquivo testado é o curta “Big Buck Bunny” da Blender Foundation, na versão “Sunflower”, disponível neste link para download gratuito no site oficial.
[File metadata]\nartist = Blender Foundation 2008, Janus Bager Kristensen 2013\nbit_rate = 3481058 bit/s\ncomment = Creative Commons Attribution 3.0 - http://bbb3d.renderfarming.net\ncompatible_brands = isomavc1\ncomposer = Sacha Goedegebure\ncreation_time = 2013-12-16T17:44:39.000000Z\nduration = 0:10:34.600000\ngenre = Animation\nmajor_brand = isom\nminor_version = 1\nstreams_nb = 3\ntitle = Big Buck Bunny, Sunflower version\n\n[Format metadata]\nextensions = mov,mp4,m4a,3gp,3g2,mj2,psp,m4b,ism,ismv,isma,f4v,avif\nlong_name = QuickTime / MOV\nname = mov,mp4,m4a,3gp,3g2,mj2\n\n[Stream #0]\ncodec_long_name = H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10\ncodec_name = h264\ncodec_tag_string = avc1\ncreation_time = 2013-12-16T17:44:39.000000Z\nduration = 0:10:34.533333\nframe_rate = 30/1\nhandler_name = GPAC ISO Video Handler\nlanguage = und\nresolution = 1920 x 1080\nstart_time = 0:00:00.066667\ntime_base = 1/30000\ntype = video\nvendor_id = [0][0][0][0]\n\n[Stream #1]\nchannels = 2\ncodec_long_name = MP3 (MPEG audio layer 3)\ncodec_name = mp3\ncodec_tag_string = mp4a\ncreation_time = 2013-12-16T17:44:42.000000Z\nduration = 0:10:34.200000\nframe_rate = 0/0\nhandler_name = GPAC ISO Audio Handler\nlanguage = und\nsample_rate = 48000 Hz\nstart_time = 0:00:00.000000\ntime_base = 1/48000\ntype = audio\nvendor_id = [0][0][0][0]\n\n[Stream #2]\nchannels = 6\ncodec_long_name = ATSC A/52A (AC-3)\ncodec_name = ac3\ncodec_tag_string = ac-3\ncreation_time = 2013-12-16T17:44:42.000000Z\nduration = 0:10:34.144000\nframe_rate = 0/0\nhandler_name = GPAC ISO Audio Handler\nlanguage = und\nsample_rate = 48000 Hz\nstart_time = 0:00:00.000000\ntime_base = 1/48000\ntype = audio\nvendor_id = [0][0][0][0]\nO arquivo de entrada é lido corretamente e a saída é o esperado: é identificado que o vídeo é do formato mp4 e as informações do formato são apresentadas, bem como alguns metadados interessantes como artist e genre. Também são impressos os metadados individuais de cada stream no arquivo, que neste caso possui um vídeo e duas trilhas de áudio.
Para complementar o exemplo anterior, podemos usar a libvlc para reproduzir o começo do arquivo em uma janela separada após exibir os metadados. Este exemplo é mais simples visto que não é necessário usar nenhuma conversão de tipos entre as linguagens, e podemos usar a libvlc diretamente no código em Haskell com as importações corretas.
É necessário ter a libvlc instalada no sistema. Em distribuições como o Ubuntu, pode-se instalar usando o apt.
$ sudo apt install libvlc-dev\nEste exemplo é baseado no código de exemplo oficial, disponível neste link.
\nÉ necessário adicionar a flag -lvlc no arquivo Cabal do projeto.
ghc-options: -- Demais flags omitidas\n -lvlc -- [!code ++]\nComo no exemplo do FFmpeg, vamos criar um módulo Vlc que fará as importações das funções de vlc/vlc.h para usarmos.
module Vlc where\n\nimport Control.Concurrent (threadDelay)\nimport Foreign\nimport Foreign.C.Types\nimport Foreign.C.String\nimport Foreign.C.ConstPtr\n\n-- Cria uma nova instância do VLC\nforeign import capi \"vlc/vlc.h libvlc_new\" c_vlcNew :: CInt -> Ptr (ConstPtr CString) -> IO (Ptr ())\n-- Cria uma mídia a partir de um caminho\nforeign import capi \"vlc/vlc.h libvlc_media_new_path\" c_vlcMediaNewPath\n :: Ptr () -> CString -> IO (Ptr ())\n-- Cria uma instância de um player a partir de uma mídia\nforeign import capi \"vlc/vlc.h libvlc_media_player_new_from_media\" c_vlcMediaPlayerNewFromMedia\n :: Ptr () -> IO (Ptr ())\n\n-- Reproduz o arquivo no player\nforeign import capi \"vlc/vlc.h libvlc_media_player_play\" c_vlcMediaPlayerPlay\n :: Ptr () -> IO ()\n-- Pausa a reprodução do arquivo no player\nforeign import capi \"vlc/vlc.h libvlc_media_player_stop\" c_vlcMediaPlayerStop\n :: Ptr () -> IO ()\n\n-- Libera da memória a mídia\nforeign import capi \"vlc/vlc.h &libvlc_media_release\" c_vlcMediaRelease\n :: FunPtr (Ptr () -> IO ())\n-- Libera da memória o player\nforeign import capi \"vlc/vlc.h &libvlc_media_player_release\" c_vlcMediaPlayerRelease\n :: FunPtr (Ptr () -> IO ())\n-- Libera da memória a instância do VLC\nforeign import capi \"vlc/vlc.h &libvlc_release\" c_vlcRelease\n :: FunPtr (Ptr () -> IO ())\nNote que iremos apenas utilizar funções já disponíveis na biblioteca do VLC, e que também não precisaremos lidar com dados visto que a biblioteca utiliza structs vazias. O importante vai ser trabalhar com os ponteiros para void.
O módulo Vlc fará um uso maior de ForeignPtr por conta de ter 3 ponteiros diferentes para utilizar e liberar da memória. Para facilitar o uso, é mais fácil criar funções auxiliares que usam tipos do Haskell em sua maioria para chamar internamente as funções do C, um conceito também conhecido como binding.
vlcNew :: CInt -> Ptr (ConstPtr CString) -> IO (ForeignPtr ())\nvlcNew argc argv = c_vlcNew argc argv >>= newForeignPtr c_vlcRelease\n\nvlcMediaNewPath :: ForeignPtr () -> String -> IO (ForeignPtr ())\nvlcMediaNewPath inst file = \n withForeignPtr inst (withCString file . c_vlcMediaNewPath) \n >>= newForeignPtr c_vlcMediaRelease\n\nvlcMediaPlayerNewFromMedia :: ForeignPtr () -> IO (ForeignPtr ())\nvlcMediaPlayerNewFromMedia media = \n withForeignPtr media c_vlcMediaPlayerNewFromMedia \n >>= newForeignPtr c_vlcMediaPlayerRelease\n\nvlcMediaPlayerPlay :: ForeignPtr () -> IO ()\nvlcMediaPlayerPlay player = withForeignPtr player c_vlcMediaPlayerPlay\n\nvlcMediaPlayerStop :: ForeignPtr () -> IO ()\nvlcMediaPlayerStop player = withForeignPtr player c_vlcMediaPlayerStop\nAssim como no módulo FFmpeg, utilizaremos as funções withForeignPtr para ter acesso a um ponteiro comum e newForeignPtr para transformar os ponteiros comuns resultantes das chamadas das funções do C para um ponteiro externo.
Nosso módulo Vlc terá apenas uma função em Haskell, a responsável por reproduzir o arquivo por um certo tempo e então liberar as instâncias da memória.
playFile :: String -> IO ()\nplayFile fileName = do\n inst <- vlcNew 0 nullPtr\n m <- vlcMediaNewPath inst fileName\n mp <- vlcMediaPlayerNewFromMedia m\n\n vlcMediaPlayerPlay mp\n threadDelay $ 10 * 1000000\n vlcMediaPlayerStop mp\n\n return ()\nNote que o código é bem semelhante a estrutura do exemplo em C, com excessão que não precisamos nos preocupar com o gerenciamento e liberação da memória dos ponteiros. As mesmas funções são chamadas e na mesma ordem, com pequenas diferenças entre as linguagens tais como o uso de threadDelay no lugar do sleep do C.
Agora podemos chamar a função playFile logo em seguida da impressão dos metadados.
main :: IO ()\nmain = do\n args <- getArgs\n \n let fileName = head args\n printMetadata fileName\n playFile fileName -- [!code ++]\nBasta adicionar a chamada de playFile logo após a impressão dos metadados.
Usaremos os mesmos comandos do stack para compilar e executar.
$ stack build\n$ LD_LIBRARY_PATH=./libs stack exec c-interop big_buck_bunny.mp4\nAo executar, pode-se observar que uma janela gráfica com o vídeo é aberta e a reprodução começa imediatamente. Após 10 segundos, o vídeo é fechado e encerrado.
\n![\"Janela](\"https://alessandrojean.github.io/posts/2024/2024-05-08-interagindo-com-bibliotecas-em-c-usando-codigo-em-haskell/vlc-screenshot.png\")
Utilizar a interoperabilidade pode ser vantajoso em casos onde é necessário performance ou se deseja utilizar uma biblioteca em código nativo já compilada e/ou disponível no sistema operacional. Através dos recursos do Haskell, torna-se fácil ter o acesso a tais funções e dados retornados visto que a linguagem já possui tal recurso implementado em seu núcleo. Apesar do código necessitar em casos mais avançados de um conhecimento intermediário em gerenciamento de memória em C, ainda assim é possível para usuários mais leigos fazer uso de funções mais simples para criar um conhecimento mais aprofundado posteriormente.
\nO Notion possui um ótimo editor WYSIWYG (What You See Is What You Get), mas por baixo dos panos todos os blocos são armazenados individualmente e o serviço não oferece uma API que permita recuperar o conteúdo inteiro de uma página em particular em formatos mais abertos, tais como o Markdown.
\n![\"Página](\"https://images.unsplash.com/photo-1642132652859-3ef5a1048fd1\")
O intuito desse tutorial é demonstrar como é possível construir um programa usando Haskell com o paradigma de programação funcional que seja capaz de pegar os blocos de uma página no Notion e convertê-los para Markdown ou outros formatos usando a API da biblioteca Pandoc.
\nApesar de um esforço existir em relação a esse problema em Haskell pelo projeto dalpd/notion no GitHub, este não possibilita (ainda) obter os blocos de uma página e está em estado muito inicial, além de estar com pouca manutenção. Este repositório citado utiliza as mesmas bibliotecas em relação ao parse da API do Notion, mas seu código difere do criado neste tutorial.
\nComo exemplo de página para testes, será utilizada a desse próprio tutorial, que será o teste do programa em conseguir converter para Markdown no formato GitHub Flavored Markdown. O repositório com o código completo encontra-se disponível em alessandrojean/notion-doc.
\nNota:
Este tutorial foi escrito como um dos projetos da disciplina Desenvolvimento Guiado a Tipos do Bacharelado em Ciência da Computação na UFABC em Março de 2024.
A ideia deste tutorial veio de uma necessidade própria de ter uma maneira de conseguir fazer um backup se necessário do conteúdo desse site. Apesar do Notion ser super versátil e aumentar bastante a produtividade na escrita, é sempre bom poder ter controle dos dados se for necessário.
\nSeguindo o recomendado para a construção de aplicações modernas com Haskell, iremos utilizar o Haskell Stack para a criação do projeto e para a manutenção das dependências externas. Todo o pacote de desenvolvimento foi instalado através do GHCup. Para iniciar a pasta do projeto, utilizamos o comando:
\n$ stack init notion-doc simple\nApós a ferramenta terminar de transferir os arquivos necessários do template simple, podemos referenciar as dependências externas no Hackage necessárias ao editar o arquivo notion-doc.cabal e incluí-las na seção build-depends:
build-depends: base >= 4.7 && < 5\n , aeson\n , aeson-casing\n , http-conduit\n , http-client\n , http-client-tls\n , http-types\n , conduit\n , conduit-extra\n , bytestring\n , pandoc\n , pandoc-types\n , slugify\nO aeson será utilizado para fazer o parse do JSON proveniente das respostas da API do Notion, enquanto o http-conduit será o cliente HTTP para fazer as requisições. Ambos são utilizados em conjunto. Por sua vez, o pandoc será utilizado para escrever o arquivo final em Markdown.
O algoritmo do programa consiste em fazer o parse dos blocos da API do Notion e convertê-los para blocos da API do Pandoc (a AST — Abstract Syntax Tree). Tendo a AST corretamente construída, é possível convertê-la para qualquer formato que o Pandoc suporte, seja ele Markdown, HTML, EPUB, dentre muitos outros.
\nO passo-a-passo, de uma forma resumida, é esse:
\naeson para as ADTs do projeto (módulo NotionApiTypes);[N.Block]) para os blocos do Pandoc ([P.Block]);Este tutorial não vai seguir necessariamente esta ordem do algoritmo, mas pretende abordar uma boa parte de como ele funciona de modo geral ao focar nas partes primordiais do código.
\nPara obter uma chave da API do Notion, é necessário criar uma integração no dashboard e conectá-la as páginas que deseja permitir seu acesso. Para fins de simplificação, a chave será escrita diretamente no código, mas evite esta abordagem em códigos para produção, visto que é totalmente insegura: use variáveis de ambiente com a biblioteca dotenv.
Para agrupar as funções da API do Notion, no programa, torna-se mais fácil criar um módulo para isso, que por enquanto terá apenas algumas constantes.
\n{-# LANGUAGE OverloadedStrings #-}\nmodule NotionApi where\n\nimport qualified Data.ByteString.Char8 as S8\n\nbaseUrl :: String\nbaseUrl = \"https://api.notion.com/v1\"\n\napiVersion :: S8.ByteString\napiVersion = \"2022-06-28\"\n\napiKey :: S8.ByteString\napiKey = \"sua_chave_da_api\"\nAqui vale uma observação: a maioria das funções do http-conduit espera como parâmetros strings do tipo ByteString e não a String do Haskell. Para evitar conversões em tempo de execução, é melhor já deixar as constantes no formato necessário.
Também faz-se uso da linguagem de extensão OverloadedStrings, que permite escrever os literais das strings diretamente (usando aspas, de modo normal) e a conversão é feita em tempo de compilação, evitando o uso recorrente do S8.pack.
As páginas no Notion são compostas por diversos tipos de blocos, podendo ser, por exemplo, parágrafos, títulos, imagens etc. Cada bloco, por sua vez, tem particularidades específicas, como o de parágrafo que permite uma edição mais detalhada do texto, possibilitando o uso de recursos como negrito, itálico e sublinhado.
\nPara obter uma boa referência de todos os tipos possíveis de blocos e suas propriedades particulares, pode-se utilizar a biblioteca @notionhq/client disponível no NPM para a linguagem JavaScript e TypeScript. Os tipos na linguagem TypeScript podem ser encontrados no arquivo src/api-endpoints.ts no repositório da biblioteca no GitHub (referência), mas também é possível consultá-los num formato mais amigável e sucinto na referência de API do Block.
Tomando como exemplo o bloco de parágrafo, temos:
\ntype ParagraphBlock = {\n type: \"paragraph\"\n paragraph: { rich_text: Array<RichTextItemResponse>; color: ApiColor }\n id: string\n has_children: boolean\n // Outras propriedades omitidas.\n}\nE tomando como exemplo um bloco de título 1, temos:
\ntype Heading1Block = {\n type: \"heading_1\"\n heading_1: {\n rich_text: Array<RichTextItemResponse>\n color: ApiColor\n is_toggleable: boolean\n }\n id: string\n has_children: boolean\n // Outras propriedades omitidas.\n}\nPor fim, o tipo genérico do bloco é do tipo soma.
\n// Outros tipos de blocos omitidos para simplificação.\ntype Block = ParagraphBlock | Heading1Block\nComo explicado anteriormente, cada tipo de bloco possui propriedades específicas. No caso do parágrafo, a propriedade paragraph é única neste bloco, enquanto propriedades como type, id e has_children são comuns em todos os blocos.
A propriedade type é a mais importante no nosso contexto, já que possibilitará a distinção do tipo do bloco, enquanto a has_children permitirá saber se será necessário fazer requisições extras para obter os blocos-filhos, no caso de blocos de listas de tópicos, por exemplo.
Em um paradigma orientado a objetos, o bloco seria uma classe abstrata, ou até mesmo uma interface, com essas propriedades que deveria ser herdado por classes para cada bloco. O desafio agora é converter estes tipos para tipos que sejam válidos na linguagem Haskell e que possibilitem o parse pela biblioteca aeson.
Todos os tipos do Notion ficarão no módulo NotionApiTypes, e alguns deles serão mostrados como exemplo nas próximas seções do texto.
aesonA biblioteca aeson, em conjunto com a aeson-casing, permite transformar strings com JSON para tipos próprios no Haskell. Os tipos, por sua vez, devem ser instâncias da classe FromJSON, onde a implementação da função parseJSON pode ser tanto manual quanto derivada automaticamente (o que será utilizado geralmente).
Suponha que temos este objeto em JSON que representa uma pessoa.
\n{\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.org\",\n \"country\": \"US\",\n \"phone\": null\n}\nPodemos representar em Haskell da seguinte maneira.
\n{-# LANGUAGE DeriveGeneric #-}\n\nimport Data.Aeson\nimport GHC.Generics (Generic)\n\ndata Person = Person\n { name :: String\n , email :: String\n , country :: String\n , phone :: Maybe String\n } deriving (Generic)\n \ninstance Person FromJSON\nAo utilizar a extensão de linguagem DeriveGeneric em conjunto com o deriving (Generic), o compilador ficará encarregado de implementar a função parseJSON automaticamente para esse tipo, poupando bastante tempo do desenvolvedor. Entretanto, isso pode ser um empecilho em alguns casos.
Suponha que uma das propriedades do objeto JSON fosse country_of_origin (em snake_case) ao invés de country, como faríamos para informar o compilador que country_of_origin deve virar countryOfOrigin para respeitar as convenções de nome do Haskell? Pior ainda, e se fosse necessário definir os atributos do tipo Person com um prefixo person para evitar ambiguidade (o que é comum neste caso do Notion), como fazer?
O primeiro caso é bem simples e pode ser resolvido sem muitas modificações com a biblioteca aeson-casing, que permite a transformação das chaves das propriedades.
{-# LANGUAGE DeriveGeneric #-}\n\nimport Data.Aeson\nimport Data.Aeson.Casing\nimport GHC.Generics (Generic)\n\ndata Person = Person\n { name :: String\n , email :: String\n , countryOfOrigin :: String\n , phone :: Maybe String\n } deriving (Generic)\n\ninstance Person FromJSON where\n parseJSON = genericParseJSON $ aesonDrop 0 snakeCase\nA função aesonDrop permite que se especifique o número de caracteres a serem removidos no início da chave e qual a transformação que deve ser aplicada, que neste caso é a snakeCase. Deste modo, a chave country_of_origin virará a countryOfOrigin. Usa-se a aesonDrop ao invés da aesonPrefix snakeCase por conta de um detalhe que será explicado em seguida.
O segundo caso também é facilmente resolvido com a aeson-casing.
{-# LANGUAGE DeriveGeneric #-}\n\nimport Data.Aeson\nimport Data.Aeson.Casing\nimport GHC.Generics (Generic)\n\ndata Person = Person\n { personName :: String\n , personEmail :: String\n , personCountryOfOrigin :: String\n , personPhone :: Maybe String\n } deriving (Generic)\n \ninstance Person FromJSON where\n parseJSON = genericParseJSON $ aesonPrefix snakeCase\nA função aesonPrefix permite que seja aplicado um transformador logo após remover um prefixo existente, que nesse caso por convenção da biblioteca são todos os caracteres em minúsculo no começo da chave. Assim que o primeiro caractere maiúsculo é encontrado, apenas o resto da string sofre a transformação. Este é o motivo de não ter sido utilizado o aesonPrefix no exemplo anterior, pois countryOfOrigin viraria of_origin apenas e daria erro no momento do parse por ser uma chave que não existe no objeto.
Em alguns casos também pode ser interessante renomear as propriedades, o que pode ser feito com functors, sendo a maneira manual de escrever o parseJSON.
import Data.Aeson\n\ndata Person = Person\n { personName :: String\n , personEmail :: String\n , personCountry :: String\n , personPhone :: Maybe String\n }\n\ninstance Person FromJSON where\n parseJSON = withObject \"Person\" $ \\v -> Person\n <$> v .: \"name\"\n <*> v .: \"email\"\n <*> v .: \"country_of_origin\"\n <*> v .?: \"phone\"\nEssa sintaxe com o functor pode parecer um pouco confusa numa primeira vez, mas ela seria equivalente a fazer isto abaixo.
\ninstance Person FromJSON where\n parseJSON = withObject \"Person\" $ \\v -> do\n name <- v .: \"name\"\n email <- v .: \"email\"\n country <- v .: \"country_of_origin\"\n phone <- v .?: \"phone\"\n \n pure $ Person name email country phone\nO argumento v é do tipo Object, que por sua vez permite que valores sejam extraídos a partir de chaves com os operadores .: e .?: para chaves opcionais.
Com essa base da biblioteca aeson, já é possível partir para alguns casos mais avançados, como o polimorfismo dos blocos a partir da propriedade type. Vamos começar definindo dois blocos iniciais, os mesmos citados como exemplo anteriormente, o parágrafo e título 1.
data Block = BlockParagraph { paragraph :: Text }\n | BlockHeading1 { heading1 :: Heading }\n deriving (Generic)\nAqui, ao invés de usarmos os atalhos da aeson-casing, precisaremos fazer algumas configurações do parser manualmente por meio de opções.
blockOptions :: Options\nblockOptions = defaultOptions \n { sumEncoding = TaggedObject { tagFieldName = \"type\", contentsFieldName = undefined }\n , constructorTagModifier = snakeCase . fixBlockType . drop 5\n , fieldLabelModifier = snakeCase . fixBlockType\n }\nExplicando cada atributo, temos:
\nsumEncoding: especifica detalhes adicionais sobre o tipo soma. Estamos informando o aeson que a diferenciação do tipo soma se dará por tags no objeto. Por padrão, o aeson utiliza a chave tag, mas como o Notion utiliza a chave type, temos que especificá-la.constructorTagModifier: faz a transformação do nome dos tipos no Haskell para os valores da propriedade type no JSON. Queremos que BlockHeading1 seja o equivalente de heading_1 no JSON, e isto é feito com a composição de funções.fieldLabelModifier: faz a transformação do nome dos atributos no Haskell para as chaves do objeto no JSON, o que a biblioteca aeson-casing faz por baixo dos panos.Em especial, temos a função fixBlockType responsável por substituir heading1 e seus derivados por heading_1, pois é um caso que a snakeCase não trata.
Tendo as opções, pode-se passá-las para o parseJSON da seguinte maneira.
instance FromJSON Block where\n parseJSON = genericParseJSON blockOptions\nOs demais tipos como Text e Heading usados nos blocos foram omitidos para fins de simplificação, mas estão disponíveis no repositório do tutorial.
Iremos utilizar dois endpoints da API do Notion: retrieve a page e retrieve block children. Em relação ao primeiro endpoint, temos os seguintes tipos de retorno:
\ndata Page = Page\n { pageId :: String\n , pageProperties :: PageProperties\n , pageCreatedTime :: String\n } deriving (Show)\n \ninstance FromJSON Page where\n parseJSON = genericParseJSON $ aesonPrefix snakeCase\nO atributo pageProperties é um mapa de String para Property (no TypeScript), e dá acesso a todos os tipos de propriedades que uma página tem, e elas são polimórficas, similar aos blocos. Como só temos interesse na propriedade do tipo title, que tem sempre a chave Name, pode-se simplificar o tipo como abaixo.
newtype PageProperties = PageProperties { propName :: TitleProperty }\n deriving (Generic)\n\ninstance FromJSON PageProperties where\n parseJSON = genericParseJSON $ aesonPrefix pascalCase\n \nnewtype TitleProperty = TitleProperty { tpTitle :: [RichTextItem] }\n deriving (Generic)\n \ninstance FromJSON TitleProperty where\n parseJSON = genericParseJSON $ aesonPrefix snakeCase\nPor sua vez, o segundo endpoint nos retorna este tipo abaixo.
\ndata PageBlocks = PageBlocks\n { results :: [Block]\n , nextCursor :: Maybe String\n , hasMore :: Bool\n } deriving (Generic)\n \ninstance FromJSON PageBlocks where\n parseJSON = genericParseJSON $ aesonDrop 0 snakeCase\nO atributo nextCursor retorna um cursor de paginação alfanumérico que pode ser utilizado para obter os próximos blocos, caso eles existam (hasMore == True).
Tendo modelado todos os tipos necessários do Notion, podemos partir para a criação das funções responsáveis por fazer as requisições HTTPS para o Notion. Voltando ao módulo NotionApi, podemos começar definindo a função retrieveNotionPage.
A função retrieveNotionPage permitirá obter detalhes de uma página a partir de seu ID, e a resposta será utilizada para obter as propriedades da página, como o título.
import Network.HTTP.Conduit\nimport Network.HTTP.Simple\nimport NotionApiTypes (Page, PageBlocks)\n\nretrieveNotionPage :: String -> IO Page\nretrieveNotionPage pageToFetch = do\n initialRequest <- parseRequest $ baseUrl ++ \"/pages/\" ++ pageToFetch\n let request\n = setRequestMethod \"GET\"\n $ addRequestHeader \"Notion-Version\" apiVersion\n $ setRequestBearerAuth apiKey initialRequest\n \n response <- httpJSON request\n return $ responseBody response\nO http-conduit funciona como uma biblioteca de cliente HTTP qualquer em outra linguagem, tal qual o OkHttp, Ktor ou o Axios. O fluxo segue o do protocolo: deve-se criar uma requisição para a URL que deseja, com o método e cabeçalhos necessários e então esperar pela resposta, que por sua vez será transformada nos tipos do Haskell pela função httpJSON. Note que o retorno da função é um IO Page, então é necessário chamar a função no mesmo contexto.
Ao utilizar a função httpJSON, o http-conduit já se encarrega de fazer a integração com o aeson e fazer o parse para o tipo do retorno informado no cabeçalho da função, que, neste caso, deve implementar a FromJSON.
De maneira similar, pode-se escrever a função retrieveBlockChildren, só alterando o retorno para IO PageBlocks e a URL do endpoint de retrieve block children.
retrieveBlockChildren :: String -> Maybe String -> IO PageBlocks\nretrieveBlockChildren blockToFetch startCursor = do\n initialRequest <- parseRequest $ baseUrl ++ \"/blocks/\" ++ blockToFetch ++ \"/children\"\n let request\n = setRequestMethod \"GET\"\n $ setRequestQueryString (blockChildrenParams startCursor)\n $ addRequestHeader \"Notion-Version\" apiVersion\n $ setRequestBearerAuth apiKey initialRequest\n\n response <- httpJSON request\n return $ responseBody response\nA diferença é que esta função permite a passagem de um parâmetro extra, o cursor de início, usado para a paginação. Desta forma, é criado um query parameter de ?start_cursor=valor quando startCursor não for Nothing.
Para facilitar obter todos os blocos de uma página sem ter que lidar com a paginação, podemos criar uma função que fará isso para nós com uma abordagem recursiva.
\nretrieveAllBlockChildren :: String -> IO [Block]\nretrieveAllBlockChildren bId = do\n first <- retrieveBlockChildren bId Nothing\n retrieveAllBlockChildren' bId (nextCursor first) (pure $ results first)\n\nretrieveAllBlockChildren' :: String -> Maybe String -> IO [Block] -> IO[Block]\nretrieveAllBlockChildren' bId (Just startCursor) bks = do\n acm <- bks\n crr <- retrieveBlockChildren bId (Just startCursor)\n retrieveAllBlockChildren' bId (nextCursor crr) (pure $ acm <> results crr)\nretrieveAllBlockChildren' _ Nothing bks = bks\nO intuito é que somente retrieveAllBlockChildren seja exportado do módulo. Esta função de entrada irá começar a recursão através de uma segunda função auxiliar. Basicamente o que é feito é obter os blocos anteriores no acumulador, obter os blocos da página atual e concatená-los. Esta nova lista de blocos é então passada para a chamada recursiva até chegar em uma resposta da API em que nextCursor seja Nothing.
Em um novo módulo Converter, criaremos as funções responsáveis por converter o Page e PageBlocks para a AST Pandoc.
Começando em uma parte crucial, vamos criar as funções responsáveis por percorrer o tipo [RichTextItem] do Notion para criar os blocos Inline do Pandoc, responsáveis pela formatação, tal como o negrito, itálico etc.
Cada item do tipo RichTextItem possui um objeto que informa quais as formatações aplicadas no pedaço do texto do item. O objeto tem o seguinte tipo.
data AnnotationResponse = AnnotationResponse\n { bold :: Bool\n , italic :: Bool\n , strikethrough :: Bool\n , underline :: Bool\n , mono :: Bool -- originalmente `code` na API\n , color :: String\n }\nVamos criar uma função que nos ajude a “anotar” um dado texto com as anotações nos tipos do Pandoc, ou seja, Inline (referência). A ideia é ser uma função recursiva que a cada propriedade como True encontrada, aplique tal formatação e defina-a como False, chamando a função novamente até que nenhuma formatação necessite ser aplicada.
{-# LANGUAGE OverloadedStrings #-}\nmodule Converter where\n\nimport qualified NotionApiTypes as N\nimport qualified Text.Pandoc.Definition as P\n\nannotate :: String -> N.AnnotationResponse -> P.Inline\nannotate txt an | N.bold an = P.Strong [annotate txt (an { N.bold = False })]\n | N.italic an = P.Emph [annotate txt (an { N.italic = False })]\n | N.strikethrough an = P.Strikeout [annotate txt (an { N.strikethrough = False })]\n | N.underline an = P.Underline [annotate txt (an { N.underline = False })]\n | N.mono an = P.Code P.nullAttr (T.pack txt)\n | otherwise = P.Str (T.pack txt)\nOs textos também podem ter links, então é necessário criar um utilitário para isso.
\nlinkify :: Maybe String -> P.Inline -> P.Inline\nlinkify Nothing txt = txt\nlinkify (Just href) txt = P.Link P.nullAttr [txt] (T.pack href, \"\")\nO tipo RichTextItem por sua vez é um tipo soma e pode ser tanto um TextRichText quanto um EquationRichText. Podemos agora escrever uma função auxiliar para converter.
parseText :: N.Text -> [P.Inline]\nparseText txt = parseInline $ N.txRichText txt\n\nparseInline :: [N.RichTextItem] -> [P.Inline]\nparseInline = map parseRichTextItem\n\nparseRichTextItem :: N.RichTextItem -> P.Inline\nparseRichTextItem (N.TextRichText txt href an _) = linkify href $ annotate txt an\nparseRichTextItem (N.EquationRichText eq _ _ _) = P.Math P.InlineMath $ T.Pack eq\nCom isso já é possível converter qualquer texto formatado do Notion para a formatação Inline do Pandoc, que é utilizada em praticamente todos os blocos. A implementação do parseRichTextItem para o tipo EquationRichText ignora a formatação nas anotações por conta que na maioria dos casos os documentos gerados pelo Pandoc não suportam tal recurso, gerando equações parecidas com o LaTeX diretamente.
Agora que é possível converter os textos, podemos começar a implementar a conversão dos blocos. Começando pelos tipos mais simples, é fácil utilizar o pattern matching do Haskell para fazer as conversões diretamente, como no código abaixo.
\nnotionToPandoc :: N.Block -> P.Block\nnotionToPandoc (N.BlockParagraph pr) = P.Para (parseText pr)\nnotionToPandoc (N.BlockHeading h1) = P.Header 1 P.nullAttr (parseHeading h1)\n-- Alguns blocos omitidos para simplificação.\n-- Casos especiais: bulleted list item e numbered list item.\nnotionToPandoc (N.BlockBulletedListItem bli) = P.Plain (parseText bli)\nnotionToPandoc (N.BlockNumberedListItem nli) = P.Plain (parseText nli)\n-- Outros blocos omitidos.\nnotionToPandoc _ = P.Para [P.Str \"Unsupported block\"]\nAqui vale uma observação em relação aos blocos de lista com marcadores e lista numerada. O Notion não possui um tipo que agrupa esses itens em um único bloco, eles são colocados sequencialmente na lista de blocos. Para isso, na conversão direta dos blocos, esses items são transformados em texto apenas, pois o texto será usado internamente no tipo de BulletList do Pandoc. É necessário, então, uma outra função que fará a conversão da lista e que possa tratar desses casos em particular.
nToP :: [N.Block] -> [P.Block]\nnToP [] = []\nnToP ((N.BlockBulletedListItem bli) : bs) = blocks\n where\n notionBlock = N.BlockBulletedListItem bli\n firstItem = notionToPandoc notionBlock\n nextItems = map ((\\b -> [b]) . notionToPandoc) $ takeWhile isBli\n finalItems = drop (length nextItems) bs\n blocks = P.BulletList ([firstItem] : nextItems) : nToP finalItems\nnToP bs = notionToPandoc (head bs) : nToP (drop 1 bs)\nA ideia é que a função nToP seja recursivamente chamada para cada bloco na lista, onde ela irá converter o primeiro bloco e concatenar em uma lista com os demais da chamada seguinte. Entretanto, se o primeiro item da lista atual for um bloco do tipo BlockBulletedListItem, será feito a conversão desse bloco e de todos os blocos seguintes na lista que forem desse mesmo tipo, que por sua vez serão adicionados dentro de um BulletList do Pandoc. Os demais itens da lista que não forem desse tipo serão convertidos normalmente pelo último pattern matching.
Para isso funcionar, é necessário uma função auxiliar que também faz uso do pattern matching para retornar se um dado bloco é do tipo BlockBulletedListItem. Isto é feito pois não há uma maneira mais direta de verificar em tempo de execução se um bloco é de dado tipo.
isBli :: N.Block -> Bool\nisBli (N.BlockBulletedListItem _) = True\nisBli _ = FalsefindNextBli _ = []\nDe modo análogo, pode-se converter os blocos do tipo BlockNumberedListItem também.
Com a conversão dos blocos implementada, podemos partir para a etapa final da criação da AST.
\ncreateAst :: N.Page -> [N.Block] -> P.Pandoc\ncreateAst page bks = P.Pandoc meta children\n where\n meta = createMeta pageProperties\n titleProp = N.propName $ N.pageProperties page\n slugH1 = slugify $ T.pack $ stripPlainText $ N.tpTitle titleProp\n header1 = P.Header 1 (slugH1, [], []) (parseInline $ N.tpTitle titleProp)\n children = header1 : createChildren bks\nA função createAst faz uso de duas funções auxiliares, uma responsável por criar os metadados do documento e outra por converter os blocos.
createMeta :: N.Page -> P.Meta\ncreateMeta (N.Page _ properties date) = P.Meta { P.unMeta = fromList metadata }\n where\n titleProp = N.propName properties\n title = T.pack $ stripPlainText $ N.tpTitle titleProp\n metadata = [\n (\"title\", P.MetaInlines [P.Str title]),\n (\"date\", P.MetaInlines [P.Str $ T.pack date])\n ]\n\ncreateChildren :: [N.Block] -> [P.Block]\ncreateChildren = nToP\nA função de criação da AST, além de converter os blocos, também adiciona um cabeçalho de nível 1 no começo da lista, que sempre será o título da página no Notion, obtido das propriedades. Tendo a AST do tipo Pandoc, fica fácil converter e criar um arquivo Markdown.
Em um novo módulo Formats, vamos implementar uma função auxiliar para escrever a conversão do tipo Pandoc em um arquivo Markdown no disco.
module Formats where\n\nimport Text.Pandoc\nimport qualified Data.Text as T\n\nmdOptions :: WriterOptions\nmdOptions = def { writerExtensions = githubMarkdownExtensions }\n\nsaveMarkdown :: String -> Pandoc -> IO ()\nsaveMarkdown fileName doc = do\n result <- runIO $ writeMarkdown mdOptions doc\n md <- handleError result\n writeFile fileName $ T.unpack md\nA função saveMarkdown executa no contexto IO a conversão da AST para ou o conteúdo final do arquivo ou um erro de conversão. Caso tudo tenha dado certo, o conteúdo é escrito no arquivo especificado por fileName. As opções mdOptions utilizam as extensões do formato GitHub Flavored Markdown, comumente adotado por diversos sites.
No módulo Main, agora torna-se fácil juntar tudo e fazer a conversão propriamente dita.
module Main (main) where\n\nimport NotionApi\nimport Converter\nimport Formats\n\ntutorialPageId :: String\ntutorialPageId = \"7b85035517424c72ab58af014fecf6bc\"\n\nmain :: IO ()\nmain = do\n page <- retrieveNotionPage tutorialPageId\n blocks <- retrieveAllBlockChildren tutorialPageId\n\n let ast = createAst page blocks\n saveMarkdown \"page.md\" ast\nA função main segue o passo-a-passo determinado anteriormente e escreve corretamente o arquivo em Markdown. Como um exemplo, pode-se observar abaixo a conversão do início do texto deste tutorial:
# Convertendo páginas do Notion para Markdown usando Haskell\n\nO [Notion](https://notion.so/) possui um ótimo editor WYSIWYG \n(*What You See Is What You Get*), mas por baixo dos panos todos \nos blocos são armazenados individualmente e o serviço não oferece\numa API que permita recuperar o conteúdo inteiro de uma página em\nparticular em formatos mais abertos, tais como o \n[Markdown](https://www.markdownguide.org/getting-started/).\nO sistema de tipos do Haskell é uma ferramenta poderosa que possibilitou a implementação de um conversor com um código com uma ótima legibilidade e com uma ótima performance. Ao ter uma AST do Pandoc, torna-se possível converter para qualquer formato que a biblioteca suporte, possibilitando um acesso fácil ao conteúdo da página no formato desejado no momento. Apesar de possuir ainda alguns recursos a serem implementados para um melhor aproveitamento da página, como usar as propriedades da página para gerar o frontmatter do Markdown, a abordagem se mostra como promissora para usos futuros.
\nNota:
Este artigo foi escrito quando o NuxtJS v3 ainda estava no estado de release candidate, fazendo com que muitas etapas do processo tivessem de ser feitas de modo manual, como depender de um módulo customizado.
Atualmente, há um módulo de terceiros criado justamente para este intuito, o nuxt-og-image, que também usa o Satori e torna o processo muito mais simples e evita complicações desnecessárias, tais como escrever o template como um componente React dentro de um projeto Vue.js. Recomendo atualmente usar este módulo.
Compartilhamento em redes sociais são uma parte importante de todo acesso que os sites possuem, e disponibilizar uma imagem como parte dos atributos do Open Graph acaba se tornando cada vez mais primordial.
\nPensando em facilitar o processo de geração destas imagens com base em algum conteúdo fixo, a Vercel acabou disponibilizando recentemente o Satori, uma biblioteca que permite a criação de arquivos SVG a partir de um componente React.
\nApesar de ser mais ligado ao ecossistema do Next.js e, por consequência, ao React, você pode utilizá-lo em qualquer projeto, seja por usar o JSX ou TSX, ou utilizar a sintaxe de objetos do React.
\n![\"Um](\"https://alessandrojean.github.io/posts/2022/2022-10-17-gerando-imagens-do-open-graph-automaticamente-com-o-satori/fea56e91-350e-4495-8a69-21bf4c37f91f.png\")
O uso da biblioteca é bem simples, mas tem algumas obrigatoriedades. Se você pretende escrever algum texto, é necessário que você providencie Buffers para as fontes que deseja que sejam utilizadas, portanto, você precisará fazer alguma requisição extra ou possuir os arquivos localmente. No lado do servidor, torna-se relativamente simples esta última opção.
\nimport { readFile } from 'node:fs/promises'\nimport { join } from 'node:path'\nimport type { SatoriOptions } from 'satori'\n\ntype FontOptions = SatoriOptions['fonts'][number]\n\nasync function loadFonts(): FontOptions[] {\n const fontsPath = join(__dirname, 'fonts')\n \n return [{\n name: 'Inter',\n data: await readFile(join(fontsPath, 'Inter-Regular.otf')),\n weight: 400,\n style: 'normal',\n }]\n}\nTendo as fontes carregadas, usar o Satori é bem fácil. A chamada da função requer dois parâmetros: um objeto ReactNode (ou o JSX/TSX direto se você configurou no seu transpilador), e as opções de renderização, onde será passado as fontes também.
import satori from 'satori'\n\nasync function createSvg(title: string): string {\n const component = (\n <div\n style={{\n height: '100%',\n width: '100%',\n display: 'flex',\n backgroundColor: 'white',\n alignItems: 'center',\n justifyContent: 'center'\n }}\n >\n { title }\n </div>\n )\n\n const options: SatoriOptions = {\n width: 800,\n height: 400,\n fonts: await loadFonts()\n }\n\n return await satori(component, options)\n}\nCom o SVG, basta utilizar alguma biblioteca como o Sharp para converter para um formato aceito pelas especificações do Open Graph, seja PNG ou JPG.
\nimport { writeFile } from 'node:fs/promises'\nimport { join } from 'node:path'\nimport sharp from 'sharp'\n\nasync function saveImage(svg: string) {\n const imagePath = join(__dirname, 'image.png')\n const image = await sharp(Buffer.from(svg))\n .png({ quality: 90 })\n .toBuffer()\n\n await writeFile(imagePath, image)\n}\nConvenientemente, o Satori também suporta alguns dos utilitários do Tailwind CSS. Para utilizá-los, basta aplicar as classes nos elementos através do atributo tw ao invés do className.
const component = (\n <div tw=\"bg-white w-full h-full flex items-center justify-center font-bold text-4xl\">\n Hello, world!\n </div>\n)\nApesar de poder utilizar o Tailwind permitir e facilitar muitas abordagens, atente-se que o Satori possui restrições de quais propriedades podem ser utilizadas no CSS. Para mais informações, consulte a documentação no GitHub.
\nA criação das imagens deste site é feita a partir de um módulo customizado para o NuxtJS. O procedimento que acabei implementando é utilizar no ambiente de prerender o hook prerender:generate para obter informações da rota que acabou de ser gerada com seu HTML.
Por sua vez, utilizo o pacote open-graph-scraper para fazer o parse desse HTML e me retornar todas as informações do Open Graph já declaradas previamente na página. É possível então extrair informações como o título, a descrição, a seção e data de publicação, repassados para o Satori no meio do template.
Apesar do Vite suportar a sintaxe do JSX/TSX, eu não consegui configurar corretamente a transpilação, então acabei optando por criar os objetos manualmente mesmo. Cada rota gera no final uma imagem no formato PNG, e a tag <meta> de og:image em ambiente de prerender ou produção aponta para ela. O nome do arquivo é gerado automaticamente a partir do pathname da rota, substituindo todas as barras por traços.
![\"Imagem](\"https://alessandrojean.github.io/posts/2022/2022-10-17-gerando-imagens-do-open-graph-automaticamente-com-o-satori/teste.webp\")
Adicionalmente eu fiz o processo ser pulado se é encontrada alguma tag <meta> de og-image:skip com valor true. Ela é útil em casos onde eu quero definir alguma imagem customizada para alguma rota ou post.
O Satori abre várias possibilidades de automação da geração de imagens de compartilhamento. Apesar de ser criado em mente para ser usado em um ambiente Next.js ou React, nada impede de ser utilizado em outros frameworks, como o NuxtJS ou Vue.js. Inclusive, imagino que eventualmente deva surgir alguma biblioteca inspirada baseada no Vue, e que tornará seu uso no NuxtJS muito mais fácil. Quem sabe em breve não teremos um @nuxtjs/og-image 😁.
Ainda preciso melhorar as imagens geradas do site, mas acredito que os resultados iniciais foram muito satisfatórios e estou realmente feliz com eles. Só de não ter que ter o trabalho de gerar uma imagem manualmente para cada novo post já tira uma etapa a mais do processo de publicação e me deixa realmente aliviado.
\nEste texto pretende ser uma continuação direta do meu texto anterior onde explico um pouco como reescrevi o código do site para utilizar o Notion como o CMS dos artigos.
\nRecapitulando um pouco, eu estava usando a API não oficial do Notion disponibilizada pela equipe da Splitbee. Originalmente ela foi criada quando a API oficial ainda estava fechada para testes e possui algumas limitações, como ser obrigatório que seus bancos de dados sejam públicos. Apesar de funcionar bem, sendo sincero, depois de um tempo eu fiquei um pouco receoso de utilizar e também percebi que por conta do cache configurado nela, novas alterações e páginas demoravam um pouco para aparecer lá, então aconteceu algumas vezes de eu precisar alterar alguma coisa e dar um rebuild no site e as alterações não estarem lá.
\nMuito bem, com essas limitações da API da Splitbee, resolvi me aventurar em utilizar a API oficial, apesar dos problemas mencionados anteriormente. Comecei seguindo o guia disponibilizado no site de desenvolvedores do Notion e criei uma integração, o que me gerou uma chave de acesso. Também ativei a integração nos bancos de dados e páginas que ela deveria ter acesso.
\nFazer as chamadas a API em um ambiente Node.js se torna relativamente fácil já que existe um cliente oficial, o @notionhq/client, que já possui todas as tipagens em TypeScript, o que facilitou bastante o trabalho. Entretanto, consumir a estrutura de dados retornada se tornou um pouco trabalhoso.
A versão atual da API não possui nenhum endpoint que retorna todos os blocos que uma página possui, já que é paginada e requer algumas chamadas para obter tudo o que você precisa. Não bastasse esse problema, o conceito de blocos do Notion permite que alguns tipos deles possam ter outros blocos dentro, e novamente, a API não retorna eles diretamente neste endpoint. Para cada bloco que possui “filhos”, você precisa chamar outro endpoint individualmente.
\nEu poderia ter abordado esta obtenção dos dados com um algoritmo recursivo, mas acabei optando por utilizar uma fila. A cada resposta da API eu percorro a lista de blocos retornados e os que tem filhos eu adiciono o id deles na fila. Enquanto a fila não está vazia, o ciclo se repete, fazendo mais chamadas a API e adicionando mais elementos na fila.
O endpoint de blocos retorna um vetor de objetos. Para facilitar um pouco o acesso a eles posteriormente, no final eu optei por transformar em uma tabela hash igual à API não oficial.
\nasync function fetchBlocksFromPage(pageId: string) {\n // Obtém a primeira página de blocos da API.\n const firstPage = await notion.blocks.children.list({\n block_id: page.id\n })\n\n const blocks = firstPage.results as BlockWithContent[]\n let nextCursor = firstPage.next_cursor\n\n // Enquanto há uma próxima página, novas chamadas são feitas.\n while (nextCursor) {\n const result = await notion.blocks.children.list({\n block_id: page.id,\n start_cursor: next_cursor\n })\n\n // No fim todos os blocos no primeiro nível estarão em blocks.\n blocks.push(...(result.results as BlockWithContent[]))\n nextCursor = result.next_cursor\n }\n\n // Lista de blocos com filhos a serem visitados.\n const blocksWithChildren = [...blocks.entries()]\n .filter(([_, block]) => block.has_children)\n .map(([i, block]) => ({ i, id: block.id }))\n\n // Enquanto há blocos a serem visitados.\n while (blocksWithChildren.length > 0) {\n // Desenfileira o primeiro bloco da fila.\n const { i, id: current } = blocksWithChildren.shift()\n \n const result = await notion.blocks.children.list({\n block_id: current\n })\n\n const children = result.results as BlockWithContent[]\n \n const newBlocksToVisit = [...children.entries()]\n .filter(([_, block]) => block.has_children)\n .map(([i, block]) => ({ i: blocks.length + i, id: block.id }))\n\n blocksWithChildren.push(...newBlocksToVisit)\n blocks.push(...children)\n blocks[i].content = children.map((child) => child.id)\n }\n\n // Transforma a lista de blocos em uma \"tabela hash\".\n return Object.fromEntries(blocks.map((b) => [b.id, b]))\n}\nAqui vale a pena ressaltar sobre o tipo BlockWithContent. Por padrão, nas tipagens do @notionhq/client, os blocos do tipo BlockObjectResponse não possuem uma propriedade content, então eu criei um tipo novo baseado nele com esta nova propriedade.
export type BlockWithContent = BlockObjectResponse & { content?: string[] }\nOutra observação importante talvez, mas nas versões atuais do cliente do Notion, por algum motivo os tipos não são exportados e não podem ser importados diretamente. Para poder acessá-las, precisei importar diretamente da pasta build/src do pacote. Provavelmente não é o método mais ideal, mas funciona enquanto eles não atualizarem o pacote para corrigir isso.
import type * as NotionApi from '@notionhq/client/build/src/api-endpoints'\nPara facilitar o acesso nos demais pontos do código, também exportei para não ter que ficar fazendo a importação de dentro do pacote do cliente em vários lugares, até para centralizar tudo.
\nexport * from '@notionhq/client/build/src/api-endpoints'\nVocê já deve ter imaginado, mas a quantidade excessiva de chamadas a API do Notion obviamente iria ter algum efeito colateral. Dependendo do tamanho e complexidade da página que você está querendo obter os blocos, a API do site (disponível somente durante o prerender e em desenvolvimento local) demora um certo tempo. Artigos extensos como o “Lendo mangás no Kindle” em alguns casos chegam a levar de 10 a 15 segundos para carregar.
\nIsto não é tanto um problema no meu caso já que o site é estático e a API só é chamada durante o build e prerender, mas para uma aplicação real com Server Side Rendering, isto poderia ser bastante problemático. O ideal neste outro caso seria configurar algum mecanismo de cache.
\nAlém disso, muito provavelmente a API do Notion possui algum rate limiting configurado, mas não cheguei a esbarrar nele ainda. Pode ser um eventual problema futuro que terei que solucionar implementando um rate limiting localmente também.
\nNão vou me adentrar no tópico da renderização dos blocos, pois só precisei fazer algumas alterações no NotionRenderer.vue, já que a base já estava pronta. Entretanto, os blocos de imagem e vídeo acabaram se tornando uma dor de cabeça bem chata.
Para quaisquer arquivos hospedados no Notion, a API retorna uma URL com expiração de acesso de uma hora. Isso acaba se tornando um problema, pois se durante o build as URLs temporárias forem utilizadas, em pouquíssimo tempo elas ficarão indisponíveis e os usuários não poderão mais vê-las. A solução para isso seria extrair essas imagens no processo de prerender e copiá-las para a pasta public, assim elas farão parte do build do site.
O Nuxt Image é um módulo oficial do NuxtJS que já se encarrega de fazer isso, porém este suporte a pré-renderização ainda não foi adicionado na v1, compatível com o NuxtJS v3. A solução então seria por enquanto eu criar meu próprio módulo local, responsável em alguma maneira de extrair as imagens dos artigos e copiá-las para a pasta public.
Eu demorei cerca de uns dois dias tentando diversas abordagens de como fazer isso, e sempre acaba esbarrando em alguma limitação do Nitro ou do h3, pacotes que o NuxtJS usa por baixo dos panos para o servidor e para o prerender. Era frustrante sempre que eu parecia estar fazendo progresso, algo do NuxtJS ou dessas bibliotecas não tinha sido completamente implementado, como diversos hooks que estão documentados, mas não são chamados em nenhum lugar.
\nA solução que eu acabei encontrando foi disponibilizar um event handler customizado no módulo que força rotas da API no servidor a implementar também um método que devolve as imagens de uma dada resposta que devem ser salvas. Assim, a cada página que o Nitro visita durante o prerender, as imagens são extraídas e adicionadas numa fila global ao processo. Quando cada página é terminada de ser renderizada, as imagens são copiadas localmente. Nesta etapa eu inclusive aproveitei para utilizar o Sharp e as convertê-las para webp.
export function addToQueue(result: ExtractorResult) {\n (global.mediaExtractorQueue as ExtractorResult[])?.push(result)\n}\n\nexport function defineExtractorEventHandler<T = any>(args: ExtractorEventHandlerArgs<T>): EventHandler<T> {\n const { handler, extract } = args\n\n return defineEventHandler(async (event) => {\n const result = await handler(event)\n const extracted = await extract(result)\n\n // TODO: Check if is the prerender env.\n addToQueue(extracted)\n\n return result\n })\n}\nNo lado do cliente, eu faço uma verificação do ambiente atual e transformo a URL do arquivo bloco. Em casos de desenvolvimento, exibo a imagem diretamente da URL temporária do Notion, mas em produção eu mapeio para a imagem copiada. Todas as imagens são salvas no formato [id-do-bloco]-[data-de-modificação].webp, então é fácil o cliente poder criar a URL correta já que ele tem tudo o que é preciso a partir das propriedades do bloco.
Como vantagem de ter criado este módulo próprio, também consegui copiar os vídeos, o que não seria possível se eu estivesse utilizando o Nuxt Image. Futuramente se precisar copiar outros arquivos que o Notion deixa serem hospedados, como PDFs, também será facilmente possível com menores alterações no código.
\nConsumir a API oficial do Notion é relativamente simples se você deixar um pouco de lado a paginação e quantidade excessiva de chamadas necessárias. Os problemas que eu esbarrei foram por conta do ecossistema do NuxtJS v3 que, no momento, ainda se encontra em release candidate, então muitos dos módulos oficiais ainda não foram atualizados. Provavelmente se você é mais adepto a utilizar outros frameworks como o Next.js, terá uma facilidade bem maior, pois ele te oferecerá um ecossistema mais estável.
\nMinha próxima aventura agora será tentar gerar as imagens do Open Graph automaticamente, similar a como o GitHub faz quando você compartilha um repositório no Twitter e uma imagem com o título, descrição e outras coisas é gerada automaticamente.
\nTe vejo numa próxima e obrigado por ler! ✌🏻
","date_published":"2022-10-15T00:00:00.000Z","date_modified":"2022-10-15T00:00:00.000Z","tags":["Programação"],"language":"pt-BR"},{"id":"utilizando-o-notion-como-um-cms","url":"https://alessandrojean.github.io/post/utilizando-o-notion-como-um-cms","title":"Utilizando o Notion como um CMS","summary":"Uma breve análise de como consegui fazer do Notion a ferramenta que uso para escrever e editar os artigos e outras seções deste site estático.","content_html":"Uma das coisas que pessoalmente me causava um pouco de cansaço quando eu utilizava o Jekyll como o gerador das duas versões anteriores do meu site era ter que lidar com todo o processo de publicação manualmente por commits e arquivos Markdown no repositório no GitHub.
\nNão me entenda mal, eu pessoalmente gosto muito da linguagem Markdown e da facilidade que ela proporciona para escrever e focar no conteúdo, mas ao longo do tempo neste projeto em específico eu fui sentindo falta de uma facilidade maior de visualizar o resultado e usar um editor WYSIWYG (What You See Is What You Get). Tudo bem que existem ótimos programas para isso focados em Markdown, como o Typora, mas nunca consegui me adaptar direito.
\nUm dia desses eu estava navegando no Twitter e me deparei com um tweet do Adam Wathan, um dos criadores do Tailwind CSS, comentando sobre a tentativa dele de usar o Notion como o CMS do site dele, e que infelizmente ele não conseguiu seguir dado a algumas limitações e a forma com que a API oficial e pública do Notion é estruturada.
\n\nBrincando um pouco com usar o Notion como um CMS para o meu site pessoal para reduzir a burocracia de publicação. É bem divertido, mas toda a abstração em ‘blocos’ e as coisas de paginação fazem ser um trabalho enorme só para extrair um conteúdo básico escrito pela API.
— Adam Wathan, Criador do Tailwind CSS
Um dos principais problemas é não haver (até o momento) um endpoint que retorne todos os blocos de uma vez ou, ainda melhor, retorne toda a página como um Markdown direto que possa ser utilizado para gerar o HTML final da página no site. Eu também cheguei a cogitar utilizar a API oficial do Notion, mas esbarrei nos exatos mesmos problemas: também achei muito excessivo a quantidade de chamadas a API que eu deveria fazer para conseguir obter todos os blocos de uma determinada página.
\n\nCerto, estou desistindo disso, é muito a se preocupar com o número de chamadas a API, rate limiting, transformar a estrutura de dados complexa que recebo de volta etc. Ainda gosto do Notion como Notion porém.
— Adam Wathan, Criador do Tailwind CSS
Felizmente consegui contornar este problema.
\nUm certo tempo antes do pessoal do Notion disponibilizar a API pública, a equipe da Splitbee criou uma API que utiliza os conceitos de serverless functions e permite acessar os conteúdos de tabelas e páginas públicas, a notion-api-worker, que está disponível para uso gratuito.
\nA API da Splitbee é muito mais prática de ser consumida e não esbarra nos problemas de paginação e nem de quantidade de requisições, ela retorna todas as páginas de uma tabela de uma vez, assim como todos os blocos de uma página.
\n[\n {\n \"id\": \"e649eca2-7309-46fc-9ca2-c246f1108dec\",\n \"Tags\": [\"notion\", \"cms\", \"nuxtjs\", \"vue.js\", \"site\"],\n \"Area\": \"Programação\",\n \"Created at\": \"2022-10-11\",\n \"Description\": \"Uma breve análise de como consegui fazer do Notion a ferramenta que uso para escrever e editar os artigos e outras seções deste site estático.\",\n \"Slug\": \"utilizando-o-notion-como-um-cms\",\n \"Name\": \"Utilizando o Notion como um CMS\"\n }\n]\nO retorno é exatamente igual às propriedades que você configura no seu banco de dados do Notion, incluindo os exatos mesmos nomes, usados como as chaves do objeto.
\n![\"Propriedades](\"https://alessandrojean.github.io/posts/2022/2022-10-11-utilizando-o-notion-como-um-cms/Untitled.png\")
Certo, então com este endpoint é relativamente fácil criar uma página que consuma os resultados e crie uma lista com todos os posts marcados como públicos (utilizando a propriedade Public que eu criei na tabela). Esta parte eu consegui fazer rapidamente no site sem maiores problemas de fato. Em compensação, a parte de montar a página de cada post foi bem mais complicada.
Se por um lado o retorno do endpoint de páginas da tabela foi bem fácil de ser consumido, o dos blocos de uma página se tornou um verdadeiro pesadelo inicialmente para mim. A resposta que a API do Splitbee retorna é um objeto que é uma espécie de HashMap que relaciona o UUID de cada bloco com seu conteúdo. Seria relativamente fácil de consumir, mas como há alguns tipos especiais de blocos que possuem outros blocos dentro, você acaba tendo que utilizar alguma abordagem recursiva, já que o HashMap no fim acaba se tornando uma árvore.
{\n\t\"e649eca2-7309-46fc-9ca2-c246f1108dec\": {\n \"role\": \"reader\",\n \"value\": {\n \"id\": \"e649eca2-7309-46fc-9ca2-c246f1108dec\",\n \"version\": 301,\n \"type\": \"page\",\n \"properties\": {},\n \"content\": [\n \"87dada78-c288-4a57-8dd0-c1dd219bbbfd\",\n \"5238f6e5-7fdd-4e9c-8f33-0e9d095aa7c7\",\n \"4c34f0e6-9d84-4032-af4a-a60df04a44af\",\n \"a5fbddb1-a537-40b4-b991-837e3dc881bc\",\n \"025eed20-014b-4ed4-8d3c-c7013a05bfcc\",\n \"255b9a9b-b8dd-404f-82a1-7f6dfb14d0cc\",\n \"a9036174-b836-4a78-aa2b-65a2ac6b8a85\",\n \"04d9f5ae-4d69-4d2e-a5d9-240839a45d2a\",\n \"56044e6e-6885-4d20-90bc-1b6544cc935c\",\n \"2a5fe49d-a944-4c57-b3d8-a69876dfc5cd\",\n \"e60e0fae-7fe3-4106-ae76-b60d4502b32c\",\n \"ce9a602c-4a9c-4956-a2a3-32a94656382f\",\n \"7ecb5844-c15e-4df0-b318-77b1da7c4906\",\n \"f78130bb-271b-48d3-b36b-9671e8d18860\"\n ],\n \"created_time\": 1665539280000,\n \"last_edited_time\": 1665541500000,\n \"parent_id\": \"dcfb4c07-20c3-43b6-9c0c-ee5f13822d80\",\n \"parent_table\": \"collection\",\n }\n },\n}\nEu tentei evitar ao máximo ter que montar manualmente a página, com certeza alguém já deve ter feito isso antes e eu não precisaria reinventar a roda. De fato, já existe um componente para Vue.js chamado vue-notion, criado pelo janniks, que inclusive já tem suporte para Nuxt JS e foi originalmente inspirado no react-notion, criado pela Splitbee.
Maravilha, então, é só utilizá-lo com algumas estilizações de CSS pelo Tailwind e eu teria acabado rapidamente o desenvolvimento das páginas, certo?
\nInfelizmente não 😢. O vue-notion ainda não é compatível com o Vue.js v3 e muito menos com o Nuxt JS 3, que trouxeram diversas modificações em suas APIs. Gostaria que fosse só esse o problema, mas ele também acaba utilizando o Prism.js para os blocos de código. Não que o Prism.js seja ruim, mas eu já fiquei um pouco cansado dele desde as outras versões do site e também queria testar algo novo, o Shiki, que utiliza o vscode-oniguruma e o vscode-textmate por baixo dos panos.
Certo, então depois de muito resistir, acabei realmente criando a página manualmente, incorporando partes do código do vue-notion e adaptando-as para o meu gosto e para a nova API de composição do Vue.js. Isso acabou dando um certo trabalho e algumas dores de cabeça devido à recursividade e algumas má-estruturações da API do Notion também.
Eu nunca tinha desenvolvido algum componente no Vue.js que utilizava recursividade, e muito menos sabia que você pode usar o mesmo componente dentro dele mesmo. Entender inicialmente o código do NotionRenderer.vue, o componente raiz que monta a página, foi complicado no começo justamente por conta disso.
<template>\n <NotionBlock v-bind=\"pass\" v-if=\"blockMap && value\">\n <NotionRenderer\n v-for=\"(contentId, contentIndex) in value.content\"\n v-bind=\"pass\"\n :key=\"contentId\"\n :level=\"level + 1\"\n :content-id=\"contentId\"\n :content-index=\"contentIndex\"\n />\n </NotionBlock>\n</template>\nPara entender o funcionamento, é necessário pensar como uma estrutura de árvore funciona. O que o componente faz é criar um bloco para si próprio, e para cada folha que este nó atual possui, é criado outra instância do NotionRenderer.vue dentro de seu corpo, usando como nó raiz desta vez o nó folha atual do loop, e assim suscetivamente para cada bloco, até que a árvore seja completamente consumida. Tenho que admitir, é um código bastante inteligente, mas que realmente é difícil de se compreender numa primeira análise.
Por sua vez, o componente NotionBlock.vue é o encarregado de renderizar cada tipo de bloco diferente, seja ele o bloco de parágrafo, o de cabeçalho, o de código e por aí vai.
<template>\n <div v-if=\"isType('page')\">\n <BlockPage v-bind=\"pass\">\n <slot />\n </BlockPage>\n </div>\n <BlockHeader\n v-else-if=\"isType(['header', 'sub_header', 'sub_sub_header'])\"\n v-bind=\"pass\"\n\t/>\n <BlockCallout v-else-if=\"isType('callout')\" v-bind=\"pass\" />\n <BlockCode v-else-if=\"isType('equation')\" v-bind=\"pass\" />\n <BlockText v-else-if=\"isType('text')\" v-bind=\"pass\" />\n <!-- E por aí vai, pra cada outro tipo de bloco existente. -->\n</template>\nNote que blocos que possuem outros blocos dentro de seu corpo, como o do tipo página ou lista, disponibilizam o <slot />, que será acessado por cada um de seus blocos interiores pela recursividade. Por conta disso, é bem fácil acabar esbarrando em problemas de recursão infinita durante o desenvolvimento, causando um pouco de estresse.
Cada componente de bloco individual possui um código específico para se adequar as necessidades de poder renderizá-lo. Deixo como exemplo o de parágrafo.
\n<template>\n <p v-if=\"properties\" :class=\"['notion-text', blockColorClass()]\">\n <BlockTextRenderer :text=\"title\" v-bind=\"pass\" />\n </p>\n <div v-else class=\"notion-blank\"> </div>\n</template>\nDe maneira similar ao NotionBlock.vue, o BlockTextRenderer.vue também percorre cada item da propriedade title do bloco para gerar o texto final, adicionando as tags necessárias como <strong>, <code>, dentre outras.
Não sei o porquê, mas o Notion não cria listas como um bloco com seus itens dentro.
\nbloco-de-lista: \n Tipo: Super bloco de lista\n Conteúdo: ['item-1', 'item-2', 'item-3']\nitem-1:\n Tipo: Bloco de lista\n Texto: Item 1\n Conteúdo: ['item-1-1']\nitem-1-1:\n Tipo: Bloco de lista\n Texto: Item 1.1\nitem-2:\n Tipo: Bloco de lista\n Texto: Item 2\nitem-3:\n Tipo: Bloco de lista\n Texto: Item 3\nAo invés disso, esta é a estrutura, sem o “super bloco”:
\nitem-1:\n Tipo: Bloco de lista\n Texto: Item 1\n Conteúdo: ['item-1-1']\nitem-1-1:\n Tipo: Bloco de lista\n Texto: Item 1.1\nitem-2:\n Tipo: Bloco de lista\n Texto: Item 2\nitem-3:\n Tipo: Bloco de lista\n\tTexto: Item 3\nIsso acaba gerando um problema semântico no HTML gerado, pois são criados vários <ul> com um item só dentro seguidos um dos outros ao invés de um <ul> só com todos os itens.
<ul>\n <li>Item 1</li>\n <ul>\n <li>Item 1.1</li>\n </ul>\n</ul>\n<ul>\n <li>Item 2</li>\n</ul>\n<ul>\n <li>Item 3</li>\n</ul>\nA maneira que eu consegui contornar isso foi percorrer a árvore de blocos e encontrar nós do tipo lista que eram seguidos um dos outros e transformar o primeiro no “super bloco” e retirar os demais do bloco raiz do tipo página, passando a responsabilidade da renderização destes itens internos do tipo lista para o BlockList.vue
<ul\n v-else-if=\"isTopLevel && type === 'bulleted_list_group'\"\n class=\"notion-list notion-list-disc\"\n>\n <li><BlockTextRenderer :text=\"title\" v-bind=\"pass\" /></li>\n <BlockNestedList v-if=\"value.content\" v-bind=\"pass\">\n <slot />\n </BlockNestedList>\n <template v-for=\"childId in properties.content\" :key=\"childId\">\n <li>\n <BlockTextRenderer\n :text=\"blockMap[childId].value.properties.title\"\n v-bind=\"pass\"\n />\n </li>\n <ul v-if=\"blockMap[childId].value.content\">\n <NotionRenderer\n v-for=\"(contentId, contentIndex) in blockMap[childId].value.content\"\n v-bind=\"pass\"\n :key=\"contentId\"\n :level=\"level + 1\"\n :content-id=\"contentId\"\n :content-index=\"contentIndex\"\n />\n </ul>\n </template>\n</ul>\nApós corrigir, o HTML gerado ficou semanticamente correto.
\n<ul>\n <li>Item 1</li>\n <ul>\n <li>Item 1.1</li>\n </ul>\n <li>Item 2</li>\n <li>Item 3</li>\n</ul>\nOutra limitação que encontrei é que o Notion não tem algumas linguagens de programação como opção em seu bloco de código. Ao contrário do Markdown onde você pode especificar manualmente uma nova opção, isso não é possível no Notion.
\nA solução que eu encontrei foi novamente percorrer a árvore de blocos atrás dos blocos de código e efetuar alguns testes usando Expressões Regulares para substituir o valor de lang. Por exemplo, para o HTML específico do Vue, eu busco por blocos que tenham lang como HTML ou JavaScript e testo a expressão /v-if|v-for|v-bind/. Se a expressão for encontrada, eu substituo lang por vue-html, assim o Shiki consegue fazer seu trabalho corretamente.
Isso abre portas para adicionar novas linguagens também, como a linguagem de tags de legendas Advanced Substation Alpha do Aegisub, que utilizo em um dos meus artigos. Na verdade, é possível adicionar qualquer nova linguagem, existente ou não, já que o Shiki consegue ler arquivos JSON de gramática no formato TextMate, assim como o VSCode.
\n{\\t($start, $end, \\fscy150)}\nO renderizador de blocos do Notion está quase perfeito, mas ainda faltam alguns tipos de blocos e algumas outras questões a serem tratadas, como o acesso a mídias. O Notion permite com que imagens sejam acessadas diretamente, mas parece que há um tempo máximo para que a validade de acesso do link expire. O ideal seria armazenar estas mídias juntamente ao repositório durante a geração do HTML, mas ainda não consegui pensar numa maneira ideal para isso.
\nEu acabei me animando tanto quanto ao resultado que até acabei convertendo a página de Sobre e de Projetos para usar o Notion também, me dando uma liberdade ainda maior para editar o conteúdo delas também sem precisar mexer com commits diretamente.
\nApós escrever ou editar páginas, eu ainda preciso dar um trigger manual na action que configurei no repositório no GitHub, mas acredito que consiga um dia automatizar isso também. Além disso, também preciso adicionar uma URL de preview para posts em rascunho.
\nDe todo modo, eu espero que utilizar o Notion como o CMS do site me dê uma maior facilidade para poder escrever e me anime mais em relação a isso. Escrever inicialmente parece dar um trabalho enorme dependendo do assunto, mas sempre acaba me ajudando a distrair (temporariamente) de problemas maiores, então é uma coisa que acaba me ajudando.
\nO intuito desse artigo não era ser um tutorial nem nada do tipo, e sim apenas um breve relato, que talvez tenha até se estendido demais. Entretanto, se lhe foi útil de alguma maneira, fico feliz.
\nAté uma próxima ✌🏻
\nNota:
Atualização: Este texto foi escrito quando o site estava utilizando a API não oficial do Notion disponibilizada pela equipe da Splitbee. Apesar de no texto eu mencionar sobre as dificuldades que a API oficial impõe, eu resolvi me aventurar e começar a utilizá-la para não depender de deixar a tabela e as páginas públicas, me dando uma liberdade e privacidade maior para os rascunhos. Você pode ler um pouco mais sobre o processo de transição neste outro artigo que eu escrevi.
Depois de alguns anos com o site parado e até fora do ar, resolvi tomar coragem e tentar refazer do zero utilizando algum outro framework que não fosse o Jekyll. Por ter mais familiaridade com o Vue.js, acabei optando pelo NuxtJS em conjunto com o Tailwind CSS, que tenho utilizado cada vez mais em meus projetos no lugar no Bulma.
\nEu só tinha usado o Tailwind em alguns projetos menores, então resolvi arriscar usar aqui também, e ainda bem que fiz esta escolha, tive uma grata surpresa. Assim como os criadores do framework alegam na descrição, realmente me senti mais produtivo em não ter que mexer em nenhuma linha de CSS fora o básico durante a configuração. Ainda tenho um pouco de dificuldades aqui e ali quanto a tentar transformar tudo em componentes o máximo que conseguir para evitar repetição de códigos, mas sinto que eventualmente conseguirei
\nNo novo site eu queria dar mais destaque e fazer parecer mais uma espécie de portfólio e currículo, com algumas informações de conhecimentos e cursos. Ao mesmo tempo, também queria trazer de volta alguns dos textos que tinha escrito nas versões anteriores do blog. Acabei retirando o de como ler mangás no Kindle por enquanto pois tive algumas mudanças de pensamento e gostaria de revisitar e tentar evitar ao máximo remeter a pirataria, dando exemplos com quadrinhos que tenham licença da Creative Comics ou sejam de código aberto, como o Pepper & Carrot.
\nOutra experiência que resolvi testar foi utilizar o Notion como o “banco de dados” dos posts. Tinha visto um dos criadores do Tailwind comentar sobre em um tweet e achei a proposta muito interessante. Infelizmente a API do Notion não retorna o corpo inteiro da página em um formato mais comum como HTML ou até mesmo Markdown, mas sim em uma espécie de AST com os nós de cada bloco. Existem alguns pacotes no NPM como o vue-notion, mas infelizmente ele não está atualizado ainda para o Vue.js v3 e nem para o NuxtJS 3, o que acaba causando diversos erros de compilação.
\nBrincando um pouco com usar o Notion como um CMS para o meu site pessoal para reduzir a burocracia de publicação. É bem divertido, mas toda a abstração em ‘blocos’ e as coisas de paginação fazem ser um trabalho enorme só para extrair um conteúdo básico escrito pela API.
— Adam Wathan, Criador do Tailwind CSS
Como eu não quis esperar com que uma atualização fosse lançada e também não queria utilizar o Prism, acabei por incorporar uma parte de seu código já adaptando a nova API de composição do Vue.js. O resultado acabou saindo bastante satisfatório, e ainda consegui aproveitar para testar um outro pacote de syntax highlighting, o Shiki, que utiliza os códigos do VSCode por baixo dos panos. A vantagem é que é possível utilizar qualquer tema do VSCode também, como meu querido Nord.
\nAinda há algumas modificações que desejo fazer no site, como colocar uma parte de projetos com alguns sites que fiz para conhecidos, mas isso será feito lentamente. Quanto aos artigos, não sei se pretendo voltar a escrever, mas ter essa facilidade de usar o Notion talvez acabe me animando um pouco por um período, vamos ver.
","date_published":"2022-10-07T00:00:00.000Z","date_modified":"2022-10-07T00:00:00.000Z","tags":["Cotidiano"],"language":"pt-BR"}]}