Repository navigation
Conteudo 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.
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.
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çã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.
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.
-
getStaticPathsgera um caminho por(locale, slug)a partir degetAllPosts, comfallback: "blocking". -
getStaticPropschamagetPostBySlug. Sem arquivo, redireciona para/blog(ou/<locale>/blog). - Se o segmento for o nome do arquivo e o post tiver
slugtraduzido, redireciona para a URL canônica (/en/blog/curso-qgis→/en/blog/free-qgis-course). Os redirects sãopermanent: false. - Serializa o MDX e passa
slug,filename,locale,mdxSourceeheadingspara 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.
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.
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.
-
getAllDocs(locale)listacontent/docs/<locale>/, com slug = nome do arquivo, ordenado pororder.getDocsBySluglê<slug>.md. Sem arquivo,getStaticPropsredireciona para/404. - O menu lateral agrupa os docs pelo campo
categorydo front matter. Só aparecem as categorias fixas emdocs/[slug].js:Docs,APIs, a de contribuição (Contribua/Contribute/Contribuir, conforme o idioma) e, só empt,Guia Central de Identidade Verbal. Um doc com outracategorynão aparece no menu. -
serializeDocaceita legenda também emButton,Warning,Tip,AccordionePDF, e o sumário incluih1. Os componentes MDX dos docs são próprios (mdxComponentsempages/docs/[slug].js), separados dos do blog. -
pttem quatro docs a mais queen/es: os do Guia Central de Identidade Verbal. Em outro idioma, essas URLs dão 404. -
getStaticPathspré-gera só os slugs dept; os demais idiomas são gerados no primeiro acesso (fallback: "blocking"). - Imagens e GIFs ficam em
public/docs/.
- A URL usa o campo
iddo front matter (getStaticPathse os links da listagem), masgetCaseStudiesByIdlê<id>.md. Oidprecisa 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 porupdated_at, mais recente primeiro. - O corpo usa os mesmos
mdxComponentsdo blog.[id].jstemrevalidate: 30. Sem arquivo no idioma, redireciona para a listagem. -
pttem quatro estudos;eneestêm sójotaelemann.
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.jsfiltra por esses nomes e traduz só o rótulo (t('categories.data')…). Uma categoria nova precisa entrar emfaqs/index.js, emfaq.jse nofaq.jsondos três idiomas. - A busca da página (
fuzzy-search) olhaquestionekeywords. - O
idvira âncora:/faq#downloadabre e rola até a pergunta (components/molecules/QuestionsBox.js). A resposta é renderizada comreact-markdown, sem MDX. -
bdpro.js,services.jsechatbot-lp.jschamam a mesma função comdir=bdPro/FAQ,services/FAQechatbot/FAQ.
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.
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.
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:
- Troca
<figure><img>por<img>nos HTMLs demedium-export/posts/. - Converte para Markdown com
medium-2-md(emmedium-export/md/), descartando posts vazios. - Gera o slug a partir do título e baixa cada imagem com Puppeteer (
headless: false, abre janela) paramedium-export/md/blog/<slug>/image_<n>.<ext>. - Reescreve as URLs das imagens para
https://storage.googleapis.com/basedosdados-website/blog/<slug>/...(o upload para o bucket é manual). - 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.
-
Post não publicado acessível pela URL:
publishedsó é checado emgetAllPosts.getPostBySlugnão checa, e comfallback: "blocking"/blog/<arquivo>renderiza mesmo compublished: false. -
Troca de idioma num post traduzido: o
LanguageSelectormantém o caminho (router.asPath). De/en/blog/free-qgis-courseparaes, o slug não existe emese a página cai na listagem. Só deptparaen/esfunciona, graças ao redirect canônico. -
og:urlfixo:blog/[slug].jsusa semprehttps://basedosdados.org/blog/${slug}, sem domínio nem prefixo do idioma. -
Menu lateral dos docs some sem subtítulos: o
Tocdedocs/[slug].jsretornanullquando o doc não tem títulos, e com ele vai a navegação entre docs. -
Categorias do blog em português:
categories.jssó tem rótulos empt, e eles aparecem assim emenees. -
Link "editar no GitHub": aponta para a branch do ambiente (
development,stagingoumain, peloNEXT_PUBLIC_BASE_URL_FRONTEND). Em produção, a edição parte demain, como pede o Fluxo de trabalho.