Skip to content

Conteudo editorial

AldemirLucas edited this page Oct 26, 2026 · 1 revision

Conteúdo editorial

Como o site lê e renderiza o conteúdo que vive no repositório: blog, documentação, estudos de caso, FAQs, guias de uso e termos. Esta página é para quem mantém o código. Para escrever um post (passo a passo, metadados, sintaxe), use o CONTRIBUTING.md. A tabela de pastas está em Estrutura do front-end, e os domínios por idioma em Internacionalização e domínios.

Visão geral

Todo conteúdo editorial segue o mesmo caminho: um .md em next/blog/<locale>/ ou next/content/<pasta>/<locale>/, lido com fs + gray-matter por uma função de pages/api/, chamada no getStaticProps da página. Nada passa por HTTP nem pelo backend. Mudou o conteúdo, precisa de deploy.

Conteúdo Arquivos Função (pages/api/) Página Renderização
Blog blog/{pt,en,es}/*.md blog/index.js blog/index.js, blog/[slug].js MDX (next-mdx-remote)
Docs content/docs/{pt,en,es}/*.md docs/index.js docs/[slug].js MDX
Estudos de caso content/caseStudies/{pt,en,es}/*.md caseStudies/index.js case-studies/index.js, case-studies/[id].js MDX
FAQs content/FAQ/, content/bdPro/FAQ/, content/services/FAQ/, content/chatbot/FAQ/ faqs/index.js faq.js, bdpro.js, services.js, chatbot-lp.js react-markdown
Guias de uso content/userGuide/{pt,en,es}/*.md datasets/getUserGuide.js dataset/[dataset].js MDX
Termos e privacidade content/termsOfService.js, privacyPolicy.js — (import direto) terms.js React + namespace terms

O mapa completo das rotas de pages/api/ está em Rotas da API Next. As de conteúdo não são endpoints: são módulos que exportam funções nomeadas.

Blog

Nome do arquivo x slug

Cada post tem duas identidades:

Campo De onde vem Para que serve
filename Nome do .md, sem extensão. É o mesmo em pt, en e es Liga as traduções de um post. Também é a pasta das imagens e o arquivo do link "editar no GitHub"
slug frontmatter.slug ou, se ausente, o filename Segmento público da URL naquele idioma

Em pt o slug é sempre o nome do arquivo. Em en e es todos os posts atuais definem slug (ex.: blog/en/curso-qgis.md → /en/blog/free-qgis-course).

Funções de pages/api/blog/index.js

Função O que faz
getAllPosts(locale) Lê blog/<locale>/, filtra por published e ordena: primeiro por order (menor primeiro), depois por date.created (mais recente primeiro)
getPostBySlug(slug, locale) Tenta <slug>.md. Se não existir, varre a pasta procurando o arquivo cujo frontmatter.slug é igual
getFilenameForSlug(slug, locale) Caminho inverso: dado o slug público, devolve o nome do arquivo
getSlugForLocale(filename, locale) Dado o nome do arquivo, devolve o slug canônico naquele idioma (ou null se não há tradução)
serializePost(content) Serializa para MDX e devolve { mdxSource, headings }

categories.js exporta o mapa analise/tutorial/institucional → rótulo, usado nos filtros de Home.js e no breadcrumb do post.

published e ambiente

getAllPosts mostra um post se published for verdadeiro ou se NEXT_PUBLIC_BASE_URL_FRONTEND for http://localhost:3000 ou https://development.basedosdados.org. Ou seja: em local e em development aparecem todos; em staging e produção só os publicados. Um post sem o campo published conta como não publicado.

Como pages/blog/[slug].js resolve uma URL

  1. getStaticPaths gera um caminho por (locale, slug) a partir de getAllPosts, com fallback: "blocking".
  2. getStaticProps chama getPostBySlug. Sem arquivo, redireciona para /blog (ou /<locale>/blog).
  3. Se o segmento for o nome do arquivo e o post tiver slug traduzido, redireciona para a URL canônica (/en/blog/curso-qgis → /en/blog/free-qgis-course). Os redirects são permanent: false.
  4. Serializa o MDX e passa slug, filename, locale, mdxSource e headings para a página.

Não há revalidate: as páginas do blog são geradas no build (ou no primeiro acesso, pelo fallback) e não se atualizam sozinhas.

MDX, componentes e ToC

serializePost usa remark-gfm, um plugin próprio de legenda e rehype-slug (gera o id dos títulos). O plugin de legenda pega o atributo caption de <Image>, <Video>, <Embed> e <Blockquote>, interpreta como Markdown e o transforma em <figcaption>.

Os componentes ficam em components/organisms/blog/Slug.js (mdxComponents): tags Markdown mapeadas para Chakra, mais Image, Video, Embed e Blockquote. Blocos de código usam highlight.js com SQL, Python, R, Bash, Stata e Markdown registrados em pages/blog/[slug].js. Outra linguagem precisa ser registrada ali.

O sumário (Toc) vem de rehypeExtractHeadings, que coleta h2 a h6 com id e calcula level = n - 2 (recuo de 5% por nível). Só aparece em telas md ou maiores e some se o post não tiver subtítulos. Um # no Markdown vira h2 visual pelo mdxComponents, mas não entra no sumário.

Imagens

Ficam em public/blog/<filename>/ e são compartilhadas entre idiomas. O post referencia com caminho absoluto (/blog/<filename>/...), inclusive no thumbnail, que vira og:image.

Documentação (/docs)

  • getAllDocs(locale) lista content/docs/<locale>/, com slug = nome do arquivo, ordenado por order. getDocsBySlug lê <slug>.md. Sem arquivo, getStaticProps redireciona para /404.
  • O menu lateral agrupa os docs pelo campo category do front matter. Só aparecem as categorias fixas em docs/[slug].js: Docs, APIs, a de contribuição (Contribua/Contribute/Contribuir, conforme o idioma) e, só em pt, Guia Central de Identidade Verbal. Um doc com outra category não aparece no menu.
  • serializeDoc aceita legenda também em Button, Warning, Tip, Accordion e PDF, e o sumário inclui h1. Os componentes MDX dos docs são próprios (mdxComponents em pages/docs/[slug].js), separados dos do blog.
  • pt tem quatro docs a mais que en/es: os do Guia Central de Identidade Verbal. Em outro idioma, essas URLs dão 404.
  • getStaticPaths pré-gera só os slugs de pt; os demais idiomas são gerados no primeiro acesso (fallback: "blocking").
  • Imagens e GIFs ficam em public/docs/.

Estudos de caso (/case-studies)

  • A URL usa o campo id do front matter (getStaticPaths e os links da listagem), mas getCaseStudiesById lê <id>.md. O id precisa ser igual ao nome do arquivo.
  • Front matter usado pelas páginas: id, displayTitle, title, thumbnail, img, imgDescription, logo (img, width, height), about, summary, sector, created_at, updated_at. A listagem ordena por updated_at, mais recente primeiro.
  • O corpo usa os mesmos mdxComponents do blog. [id].js tem revalidate: 30. Sem arquivo no idioma, redireciona para a listagem.
  • pt tem quatro estudos; en e es têm só jota e lemann.

FAQs

getAllFAQs(locale, dir = "FAQ") lê content/<dir>/<locale>/. Cada arquivo tem question, categories, keywords, id e, opcionalmente, order. A ordem é: itens com order primeiro; depois pela primeira categoria, na sequência Dados, Planos Pagos, BigQuery, BD Lab, BD Edu, Institucional; depois pela pergunta, em ordem alfabética.

  • As categorias ficam em português em todos os idiomas: faq.js filtra por esses nomes e traduz só o rótulo (t('categories.data')…). Uma categoria nova precisa entrar em faqs/index.js, em faq.js e no faq.json dos três idiomas.
  • A busca da página (fuzzy-search) olha question e keywords.
  • O id vira âncora: /faq#download abre e rola até a pergunta (components/molecules/QuestionsBox.js). A resposta é renderizada com react-markdown, sem MDX.
  • bdpro.js, services.js e chatbot-lp.js chamam a mesma função com dir = bdPro/FAQ, services/FAQ e chatbot/FAQ.

Guias de uso (content/userGuide)

Não têm rota própria. O backend devolve usageGuide no dataset, e dataset/[dataset].js chama getUserGuide(usageGuide, locale), que lê content/userGuide/<locale>/<usageGuide>.md. O sumário considera só h1. user_guide_model.md é o modelo para novos guias.

Termos e política de privacidade

content/termsOfService.js e content/privacyPolicy.js são componentes React, não Markdown. O texto está no namespace terms de public/locales/<locale>/terms.json, então mudar os termos é editar as traduções, não o componente.

scripts/migrate-posts.mjs

Script avulso, usado na migração do blog do Medium. Não está em package.json e não roda no build. As instruções estão no topo do arquivo: exportar os dados do Medium, salvar medium-export.zip em next/ e descompactar em next/medium-export/. Depois, node scripts/migrate-posts.mjs a partir de next/.

O que ele faz:

  1. Troca <figure><img> por <img> nos HTMLs de medium-export/posts/.
  2. Converte para Markdown com medium-2-md (em medium-export/md/), descartando posts vazios.
  3. Gera o slug a partir do título e baixa cada imagem com Puppeteer (headless: false, abre janela) para medium-export/md/blog/<slug>/image_<n>.<ext>.
  4. Reescreve as URLs das imagens para https://storage.googleapis.com/basedosdados-website/blog/<slug>/... (o upload para o bucket é manual).
  5. Grava blog/<slug>.mdx.

Hoje ele não serve para publicar post novo: grava .mdx na raiz de blog/, fora das pastas de idioma, e o blog só lê blog/<locale>/*.md. Nenhum post atual referencia o bucket; as imagens estão em public/blog/. Trate como histórico.

Pontos de atenção

  • Post não publicado acessível pela URL: published só é checado em getAllPosts. getPostBySlug não checa, e com fallback: "blocking" /blog/<arquivo> renderiza mesmo com published: false.
  • Troca de idioma num post traduzido: o LanguageSelector mantém o caminho (router.asPath). De /en/blog/free-qgis-course para es, o slug não existe em es e a página cai na listagem. Só de pt para en/es funciona, graças ao redirect canônico.
  • og:url fixo: blog/[slug].js usa sempre https://basedosdados.org/blog/${slug}, sem domínio nem prefixo do idioma.
  • Menu lateral dos docs some sem subtítulos: o Toc de docs/[slug].js retorna null quando o doc não tem títulos, e com ele vai a navegação entre docs.
  • Categorias do blog em português: categories.js só tem rótulos em pt, e eles aparecem assim em en e es.
  • Link "editar no GitHub": aponta para a branch do ambiente (development, staging ou main, pelo NEXT_PUBLIC_BASE_URL_FRONTEND). Em produção, a edição parte de main, como pede o Fluxo de trabalho.

Clone this wiki locally