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 14+ estilos (ABNT, APA, Vancouver, etc.) - sem precisar instalar nada:

• Busca automatica por DOI, ISBN ou titulo
• Importacao de curriculo Lattes
• Exportacao para Word, BibTeX, RIS
• 100% gratuito para estudantes

Experimente o CiteMe gratuitamente

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 *et al.*, 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. *et al.* Titulo. 2023."

formatEtAl(): string

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

formatEtAl(); // -> "*et al.*"

formatCirca(): string

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

formatCirca(); // -> "*ca.*"

// Usado quando o ano exato e desconhecido:
// [*ca.* 2020] ou (*ca.* 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.

Contribuindo

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

Licenca

MIT - Desenvolvido com carinho pelo time CiteMe