abnt-citation

O primeiro parser brasileiro de citacoes academicas conforme ABNT NBR 10520:2023 e NBR 6023:2025.

Este pacote foi extraido do CiteMe - o gerenciador de citacoes academicas mais completo do Brasil.

English version

---

Quer formatacao automatica sem codigo?

CiteMe formata suas referencias automaticamente em 40+ estilos (ABNT, APA, Vancouver, Chicago, IEEE, MLA e mais) - sem precisar instalar nada:

• Busca em 8+ bases academicas (OpenAlex, PubMed, SciELO, Semantic Scholar e mais - 200M+ artigos)
• Fontes verificadas de bases reais - zero risco de alucinacao de IA
• Extensao para Chrome/Firefox, add-in para Word e Google Docs
• Importacao/exportacao em BibTeX e RIS
• Plano gratuito disponivel - sem cartao de credito

Experimente o CiteMe

---

Por que este pacote existe?

A ABNT atualizou as normas de citacoes e referencias:

• NBR 10520:2023 - Mudou como nomes de autores aparecem em citacoes
• NBR 6023:2025 - Atualizou regras para referencias (ISSN opcional, "ca." em italico, etc.)

Tipo de autor	Antes (2002)	Depois (2023/2025)
Pessoa	(SILVA, 2023)	(Silva, 2023)
Instituicao	(IBGE, 2023)	(IBGE, 2023)

Nenhum parser existente (Zotero, Mendeley, citation-js) implementa essas regras corretamente porque:

1. CSL (Citation Style Language) nao suporta pos-processamento condicional
2. Requer uma lista de acronimos protegidos (IBGE, USP, UNESCO, etc.)
3. Requer heuristicas para detectar acronimos desconhecidos

Este pacote resolve esse problema com zero dependencias e < 10KB.

Instalacao

npm install abnt-citation

Quick Start

import { formatAuthorABNT2023, postProcessABNT2023 } from 'abnt-citation';

// Formata nomes de autores individuais
formatAuthorABNT2023('SILVA');    // -> "Silva"
formatAuthorABNT2023('IBGE');     // -> "IBGE"
formatAuthorABNT2023('DA SILVA'); // -> "Da Silva" (particula maiuscula no inicio)

// Pos-processa citacoes completas
postProcessABNT2023('(SILVA, 2023)', true);           // -> "(Silva, 2023)"
postProcessABNT2023('(SILVA; IBGE, 2023)', true);     // -> "(Silva; IBGE, 2023)"
postProcessABNT2023('(SILVA et al., 2023)', true);    // -> "(Silva <i>et al.</i>, 2023)"
postProcessABNT2023('(SILVA apud SANTOS, 2023)', true); // -> "(Silva apud Santos, 2023)"

API Completa

Formatacao ABNT (NBR 10520:2023 + NBR 6023:2025)

formatAuthorABNT2023(author: string): string

Formata um nome de autor conforme ABNT 2023:

• Pessoas: Converte para Title Case (SILVA -> Silva)
• Instituicoes/Acronimos: Mantem em MAIUSCULAS (IBGE -> IBGE)
• Particulas portuguesas: Minusculas exceto no inicio (MARIA DA SILVA -> Maria da Silva, DA SILVA -> Da Silva)

formatAuthorABNT2023('SILVA');            // "Silva"
formatAuthorABNT2023('IBGE');             // "IBGE"
formatAuthorABNT2023('DA SILVA');         // "Da Silva" (particula no inicio)
formatAuthorABNT2023('MARIA DA SILVA');   // "Maria da Silva"
formatAuthorABNT2023("O'BRIEN");          // "O'Brien"
formatAuthorABNT2023('SMITH-JONES');      // "Smith-Jones"
formatAuthorABNT2023('OLIVEIRA E SILVA'); // "Oliveira e Silva"

postProcessABNT2023(citation: string, isInText: boolean): string

Pos-processa citacoes formatadas pelo CSL:

// Citacoes parenteticas (isInText = true)
postProcessABNT2023('(SILVA, 2023)', true);
// -> "(Silva, 2023)"

postProcessABNT2023('(SILVA; SANTOS, 2023)', true);
// -> "(Silva; Santos, 2023)"

postProcessABNT2023('(SILVA, 2023, p. 45)', true);
// -> "(Silva, 2023, p. 45)"

postProcessABNT2023('(SILVA apud SANTOS, 2023)', true);
// -> "(Silva apud Santos, 2023)"

// Bibliografia (isInText = false) - apenas formata et al.
postProcessABNT2023('SILVA, J. et al. Titulo. 2023.', false);
// -> "SILVA, J. <i>et al.</i> Titulo. 2023."

formatEtAl(): string

Retorna "et al." formatado em italico (HTML):

formatEtAl(); // -> "<i>et al.</i>"

formatCirca(): string

Retorna "ca." (circa) formatado em italico conforme NBR 6023:2025:

formatCirca(); // -> "<i>ca.</i>"

// Usado quando o ano exato e desconhecido:
// [<i>ca.</i> 2020] ou (<i>ca.</i> 2020)

Deteccao de Acronimos

isProtectedAcronym(author: string): boolean

Verifica se um nome e um acronimo protegido:

isProtectedAcronym('IBGE');    // true
isProtectedAcronym('USP');     // true
isProtectedAcronym('UNESCO');  // true
isProtectedAcronym('NASA');    // true (heuristica)
isProtectedAcronym('SILVA');   // false
isProtectedAcronym('LEE');     // false (sobrenome curto conhecido)

addProtectedAcronym(acronym: string): void

Adiciona um acronimo customizado a lista:

addProtectedAcronym('ACME');
isProtectedAcronym('ACME'); // true

addProtectedAcronyms(acronyms: string[]): void

Adiciona multiplos acronimos:

addProtectedAcronyms(['ACME', 'CORP', 'INC']);

Parser de Nomes Brasileiros

parseNameToCsl(name: string): CslName

Converte nome para formato CSL com suporte a convencoes brasileiras:

parseNameToCsl('Joao Silva Filho');
// -> { family: "Silva Filho", given: "Joao" }

parseNameToCsl('Maria da Costa e Silva');
// -> { family: "da Costa e Silva", given: "Maria" }

parseNameToCsl('SANTOS, Jose Carlos');
// -> { family: "SANTOS", given: "Jose Carlos" }

extractFamilyName(displayName: string): string

Extrai apenas o sobrenome:

extractFamilyName('Joao Silva Filho'); // -> "Silva Filho"
extractFamilyName('Maria da Costa');   // -> "da Costa"

extractGivenName(displayName: string): string

Extrai apenas o prenome:

extractGivenName('Joao Silva Filho'); // -> "Joao"
extractGivenName('Maria da Costa');   // -> "Maria"

isPortugueseParticle(word: string): boolean

Verifica se e uma particula portuguesa:

isPortugueseParticle('da');  // true
isPortugueseParticle('de');  // true
isPortugueseParticle('e');   // true
isPortugueseParticle('Silva'); // false

isBrazilianSuffix(word: string): boolean

Verifica se e um agnome brasileiro:

isBrazilianSuffix('Filho');   // true
isBrazilianSuffix('Neto');    // true
isBrazilianSuffix('Junior');  // true
isBrazilianSuffix('Silva');   // false

Constantes Exportadas

import {
  PROTECTED_ACRONYMS,   // Set<string> - 150+ siglas brasileiras
  SHORT_SURNAMES,       // Set<string> - Sobrenomes curtos (LEE, WU, LIMA, etc.)
  BRAZILIAN_SUFFIXES,   // Set<string> - Agnomes (FILHO, NETO, JUNIOR, etc.)
  PORTUGUESE_PARTICLES, // Set<string> - Particulas (da, de, do, das, dos, e)
  PREFIX_PARTICLES,     // Set<string> - Particulas de prefixo (da, de, do, das, dos)
  CONNECTOR_PARTICLES,  // Set<string> - Particula conectora (e)
} from 'abnt-citation';

Integracao com citation-js

import Cite from 'citation-js';
import { postProcessABNT2023 } from 'abnt-citation';

const cite = new Cite(references);

// Gera citacao no estilo ABNT
const citation = cite.format('citation', {
  format: 'text',
  template: 'abnt',
  lang: 'pt-BR',
});

// Aplica regras ABNT 2023
const formatted = postProcessABNT2023(citation, true);

Usado em Producao

Este pacote e o motor de formatacao ABNT 2023 do CiteMe, usado por milhares de estudantes brasileiros para gerar referencias academicas corretas.

Ecossistema CiteMe

O CiteMe oferece ferramentas para todo o fluxo de trabalho academico:

Produto	Descricao
Web App	Gerador de referencias com busca em 8+ bases academicas
Extensao Chrome/Firefox	Cite qualquer pagina ou artigo com um clique
Add-in Word	Insira citacoes direto no Microsoft Word
Add-on Google Docs	Integre referencias no Google Docs
abnt-citation (este pacote)	Motor open-source de formatacao ABNT 2023

Contribuindo

Contribuicoes sao bem-vindas! Por favor, abra uma issue ou pull request no GitHub.

Licenca

MIT - Desenvolvido pelo time CiteMe