Markdown Links
Índice
- 1. Resumo do projeto
- 2. Como instalar o módulo
- 3. Informações da aplicação
- 4. Fluxograma
- 5. Testes
- 6. Tecnologias utilizadas
- 7. Contato
1. Resumo do projeto
Markdown é uma linguagem de marcação muito popular entre os programadores. É usada em muitas plataformas que manipulam texto (GitHub, fórum, blogs e etc) e é muito comum encontrar arquivos com este formato em qualquer repositório (começando pelo tradicional README.md).
Os arquivos Markdown
normalmente contém links que podem estar
quebrados, ou que já não são válidos, prejudicando muito o valor da
informação que está ali.
O objetivo desta aplicação foi desenvolver uma ferramenta de linha de comando (CLI) que lê e analisa arquivos no formato
Markdown
, para verificar os arquivos que contenham links e mostrar algumas estatísticas para obter informações relevantes desses links. A biblioteca tem como objetivo de ser utilizada por linha de comando, porém também pode ser importado com require
para ser utilizado em outros códigos. A biblioteca e script executável foram implementados em JavaScript para serem executadas com Node.JS.
2. Como instalar o módulo
Utilize o seguinte comando no terminal:
$ npm i md-links-mnds
Verifique se você contém arquivos markdown locais para a execução.
OBS: Os arquivos markdown válidos contém as seguintes extensões: '.md', '.mkd', '.mdwn', '.mdown', '.mdtxt', '.mdtext', '.markdown', '.text'.
3. Informações da aplicação:
1) JavaScript API
O módulo deve ser importado em outros scripts Node.js e oferece a seguinte interface:
mdLinks(path, options)
Argumentos
-
path
: Rota ao arquivo ou diretório. -
options
: Um objeto com a seguinte propriedade:-
validate
: Um booleano que determina se deseja validar os links encontrados. -
stats
: Booleano que determina se deseja obter um output com informações estatísticas gerais.
-
Valor de retorno
A função retorna uma promessa (Promise
) que
resolve um array de
objetos, onde cada objeto representa um link, contendo as seguintes
propriedades:
Com validate:false
:
-
href
: URL encontrada. -
text
: Texto que irá aparecer dentro de um link (<a>
). -
file
: Rota do arquivo onde foi encontrado o link.
Com validate:true
:
-
href
: URL encontrada. -
text
: Texto que aparecía dentro del link (<a>
). -
file
: Ruta del archivo donde se encontró el link. -
status
: Código de resposta HTTP. -
ok
: Mensagemfail
em caso de falha ouok
em caso de sucesso.
Exemplo
const mdLinks = require("md-links");
mdLinks("./some/example.md")
.then(links => {
// => [{ href, text, file }, ...]
})
.catch(console.error);
mdLinks("./some/example.md", { validate: true })
.then(links => {
// => [{ href, text, file, status, ok }, ...]
})
.catch(console.error);
mdLinks("./some/dir")
.then(links => {
// => [{ href, text, file }, ...]
})
.catch(console.error);
2) CLI (Command Line Interface - Interface de Linha de Comando)
Executando na CLI
O executável da aplicação pode ser executado da seguinte maneira, através do terminal:
$ md-links <path-to-file>
Valor de retorno:
-
href
: URL encontrada. -
text
: Texto que aparecia dentro do link (<a>
). -
file
: Rota do arquivo onde foi encontrado o link.
Validando os links
Para obter informações mais precisas do estado atual dos links, você pode adicionar a opção --validate:
$ md-links <path-to-file> --validate
Valor de retorno:
-
href
: URL encontrada. -
text
: Texto que aparecia dentro do link (<a>
). -
file
: Rota do arquivo onde foi encontrado o link. -
status
: Código de resposta HTTP. -
ok
: Mensagemfail
em caso de falha ouok
em caso de sucesso.
Verificando links totais e únicos
Se você precisa verificar a quantidade de links, adicione a opção --stats:
$ md-links <path-to-file> --stats
Valor de retorno:
-
Total
: Total de links encontrados no arquivo/diretório. -
Unique
: Quantidade de links únicos (que não se repetem).
Combinando --stats e --validate
Utilize essa combinação para verificar, além da quantidade, os links quebrados:
$ md-links <path-to-file> --stats --validate
Valor de retorno:
-
Total
: Total de links encontrados no arquivo/diretório. -
Unique
: Quantidade de links únicos (que não se repetem). -
Broken
: Quantidade de links quebrados.
4. Fluxograma
Um fluxograma foi definido antes do código para definir os próximos passos e organização do projeto.
5. Testes
- Foi utilizado o Jest para a execução dos testes unitários.