html-gen-docs

CLI to convert Markdown files to HTML and serve the generated documentation on a local server.

Installation

Global (npm)

npm install -g html-gen-docs

After that, use html-gen from any directory on your machine.

Global (Bun)

bun add -g html-gen-docs

Without global installation

npx html-gen-docs --input docs --output docs-html

Quick usage

Convert and serve with explicit values:

html-gen --input docs/ --output docs-html/ --port 12334

Convert the current directory to a temp output with an auto-selected port:

html-gen

Use a specific visual theme:

html-gen --input docs/ --output docs-html/ --theme dark

Serve multiple source directories as a unified documentation site:

html-gen --input docs/ crm/ wiki/ --output html/ --theme nord

Each directory becomes a top-level folder in the output. The index shows them side-by-side.

Clean the output directory before generating (removes stale files):

html-gen --input docs/ --output docs-html/ --clean

Show help:

html-gen --help

Show version:

html-gen --version

Available options

| Option | Short | Description | Default | |---|---|---|---| | --input <dir...> | -i | Source directory (or directories) with .md files | Current directory | | --output <dir> | -o | Output directory for generated HTML | System temp dir | | --port <port> | -p | Port for the local server | Auto-selected | | --theme <name> | -t | Visual theme (see Themes) | default | | --clean | -c | Empty the output directory before generating | false | | --help | -h | Show help | — | | --version | -v | Show version | — |

Default behavior:

• --output not specified → Linux: /tmp/<timestamp>-<random>/ · Windows: C:\Temp\<timestamp>-<random>\
• --port not specified → first available port is used automatically
• --theme not specified → default (light, clean)

Usage as a development dependency

If you want to pin the tool version within a project:

npm install --save-dev html-gen-docs

Add a script to your package.json:

{
  "scripts": {
    "docs:serve": "html-gen --input docs/ --output docs-html/ --port 12334"
  }
}

Run with:

npm run docs:serve

Supported features

• Recursive conversion of .md to .html
• Original folder structure preserved
• Multiple input directories: pass two or more paths to --input; each becomes a top-level folder
• YAML frontmatter with tolerant fallback for loose format
• Mermaid (```mermaid block and ::: mermaid syntax) — responsive, adaptive height
• MathJax 4 for mathematical formulas
• Highlight.js for code with theme-matched syntax highlighting
• Express server with navigable listing of generated HTML files
• File and folder metadata sourced from original .md files
• node_modules automatically excluded from file counts
• Automatic real-time updates with file watcher (.md only) and hot-reload via SSE — browser refreshes without manual reload
• Terminal logs with friendly progress and access URL
• --clean flag to remove stale output files before generation
• 9 built-in themes selectable via --theme — applied to both document pages and the file-browser index
• Font scaling: A− / A+ buttons on every page to shrink or enlarge text globally; preference persisted in localStorage
• All Files mode: single button to list every document across all folders, with a folder column to show the origin of each file
• Search: find documents by filename or content; results show match badges and a content snippet; automatically activates All Files mode from the root index; when inside a folder, results are scoped to that folder and its subfolders

Themes

Select a theme with --theme <name>. The theme is applied to both the generated document pages and the file-browser index.

| Theme | Style | |---|---| | default | Clean light — neutral grays, indigo accent | | dark | Dark blue-gray — violet/cyan gradient | | github | GitHub-flavored light — familiar and readable | | retro | Warm sepia, serif fonts, typewriter feel | | dracula | Classic Dracula palette — purple/pink/cyan | | nord | Arctic cool — muted blue-gray palette | | catppuccin | Pastel Mocha — soft and friendly | | solarized | Solarized Dark — amber/green on blue-gray | | corporate | Clean professional light — slate/blue |

Each theme ships its own highlight.js stylesheet (matched by style), Mermaid diagram theme, and Google Fonts pairing.

html-gen --input docs/ --output html/ --theme dracula

Multiple input directories

Pass two or more directories to --input to merge them into a single documentation site:

html-gen --input docs/ crm/ wiki/ --output html/

Single input (default): output mirrors the source directory structure directly inside --output.

Multiple inputs: each source directory becomes a sub-folder in --output named after the directory itself:

--input docs/ crm/  →  html/docs/…  +  html/crm/…

The index page shows docs/ and crm/ as top-level folders. The search and All Files mode span all of them. The file watcher monitors each directory independently and hot-reloads the browser on any change.

Navigation features

Font scaling

Every page has A− and A+ buttons next to the Index and Top links. Clicking them decreases or increases the global text size in six steps (80 % → 90 % → 100 % → 110 % → 120 % → 135 %). The chosen scale is saved in localStorage and restored on the next page load with no flash of unstyled content.

All Files mode

Click 📋 Todos os Arquivos in the listing toolbar to see every generated document from all folders in a single flat table. A Pasta (Folder) column shows the origin folder for each file. Click the button again to return to the normal folder view.

Search

Type a term in the search bar and press Enter or click 🔎 Buscar.

• Searches match against file names and file content (stored in memory from the original .md sources).
• Results show a badge indicating whether the match was in the name, the content, or both, plus a short snippet of the matched text.
• If you are on the root index, the search automatically switches to All Files mode so results span the entire documentation.
• If you are inside a folder (e.g. /guias), results are scoped to that folder and its subfolders.
• The watcher keeps the content index up to date: any .md file that is added, modified, or deleted is reflected in the next search without restarting the server.
• Click ✖ Limpar to clear the search and return to the previous view.

Project structure

bin/
  html-gen.js                # global CLI entrypoint
src/
  app/run.js                 # main orchestration
  cli/parse-args.js          # argument parsing and validation
  config/
    runtime-config.js        # path resolution and defaults
    temp-output.js           # OS-specific temp directory
  conversion/
    discovery.js             # recursive markdown discovery
    converter.js             # markdown → html pipeline
  html/template.js           # final HTML page template
  markdown/
    frontmatter.js           # frontmatter parser with fallback
    renderer.js              # markdown-it + plugins
  server/
    directory-listing.js     # HTML listing of generated files
    start-server.js          # Express server initialization
test/
  *.test.js                  # automated tests (node:test)
docs/
  teste-completo.md          # full markdown document for render validation

Development

Install dependencies:

npm install

Run tests:

npm test

Run locally:

npm start -- --input docs --output docs-html --port 12334

With Bun:

bun ./bin/html-gen.js --input docs --output docs-html

CI/CD on GitLab

The project includes a pipeline in .gitlab-ci.yml with two stages:

• test: runs npm test on branches and merge requests
• release: runs npm run release on the main branch (semantic-release)

For automatic npm publishing, configure the following GitLab CI/CD variables:

• NPM_TOKEN: npm automation token with publish permission
• GL_TOKEN: GitLab personal access token (scope api)

FAQ

1. The command did not find any markdown files. What should I do?

Check that the directory specified with --input exists and contains .md files.

2. Do I always need to specify --output?

No. Without --output, the tool creates a temporary directory automatically.

3. Can I use it with both Node and Bun?

Yes. The package is implemented in CommonJS with libraries compatible with both runtimes.

4. The port is already in use. How to fix it?

Specify another port with --port, or omit it to use a free port automatically.

5. Does the tool watch for changes in real time?

Yes. After the initial publish, the watcher monitors .md file changes, reconverts them automatically, and prints the URL in the terminal.

6. The file counts seem wrong for a folder with scripts or dependencies. Why?

The tool only counts .md files and automatically excludes node_modules directories from all counts and size calculations.

7. How do I guarantee fresh data with no stale HTML?

Use --clean to empty the output directory before every run:

html-gen --input docs/ --output docs-html/ --clean

8. How does the search know about file content?

At startup, the tool reads all .md source files into an in-memory index. The file watcher keeps this index current: edits, new files, and deletions are reflected immediately without restarting the server.

9. How do I search only within a specific folder?

Navigate to the folder first (e.g. open http://localhost:PORT/?path=guias), then use the search bar. Results will be limited to that folder and its subfolders.

10. How do I choose a visual theme?

Use --theme <name> when starting the tool. For example: html-gen --input docs/ --theme dark. See the Themes section for all available options.

11. Can I serve multiple documentation directories at once?

Yes. Pass all directories after --input:

html-gen --input docs/ crm/ wiki/ --output html/

Each directory becomes a top-level folder in the output, and the index lists them all together.

12. How does the font scaling work?

Every page has A− and A+ buttons in the top bar. Clicking them cycles the font size between six steps (80 % to 135 %). The preference is saved in localStorage and restored on the next visit — including when switching between the index and document pages.

Additional documentation

• Detailed API: docs/API.md
• Contributing guide: CONTRIBUTING.md
• Change history: CHANGELOG.md
• Publishing to npm: docs/npm-publish-guide.md

License

ISC

html-gen-docs (Português)

CLI para converter arquivos Markdown em HTML e publicar a documentação gerada em um servidor local.

Instalação

Global (npm)

npm install -g html-gen-docs

Depois disso, use html-gen em qualquer pasta da máquina.

Global (Bun)

bun add -g html-gen-docs

Sem instalação global

npx html-gen-docs --input docs --output docs-html

Uso rápido

Converter e servir com valores explícitos:

html-gen --input docs/ --output docs-html/ --port 12334

Converter a pasta atual para saída temporária e porta automática:

html-gen

Usar um tema visual específico:

html-gen --input docs/ --output docs-html/ --theme dark

Servir múltiplas pastas de origem como um site unificado:

html-gen --input docs/ crm/ wiki/ --output html/ --theme nord

Cada pasta vira uma subpasta de nível raiz na saída. O índice exibe todas juntas.

Limpar o diretório de saída antes de gerar (remove arquivos obsoletos):

html-gen --input docs/ --output docs-html/ --clean

Mostrar ajuda:

html-gen --help

Mostrar versão:

html-gen --version

Opções disponíveis

| Opção | Curta | Descrição | Padrão | |---|---|---|---| | --input <pasta...> | -i | Pasta(s) de origem com arquivos .md | Pasta atual | | --output <pasta> | -o | Pasta de saída para os HTML gerados | Pasta temporária do sistema | | --port <porta> | -p | Porta do servidor local | Automática | | --theme <nome> | -t | Tema visual (veja Temas) | default | | --clean | -c | Esvazia a pasta de saída antes de gerar | false | | --help | -h | Exibe a ajuda | — | | --version | -v | Exibe a versão | — |

Comportamento padrão:

• Sem --output → Linux: /tmp/<timestamp>-<random>/ · Windows: C:\Temp\<timestamp>-<random>\
• Sem --port → a primeira porta disponível é usada automaticamente
• Sem --theme → default (claro, limpo)

Uso como dependência de desenvolvimento

Se você quer versionar o uso da ferramenta dentro de um projeto:

npm install --save-dev html-gen-docs

No package.json, adicione um script:

{
  "scripts": {
    "docs:serve": "html-gen --input docs/ --output docs-html/ --port 12334"
  }
}

Execute com:

npm run docs:serve

Recursos suportados

• Conversão recursiva de .md para .html
• Preservação da estrutura de pastas
• Múltiplas pastas de entrada: passe dois ou mais caminhos em --input; cada um vira uma pasta de nível raiz
• Frontmatter YAML com fallback tolerante para formato solto
• Mermaid (bloco ```mermaid e sintaxe ::: mermaid) — responsivo, altura adaptativa
• MathJax 4 para fórmulas matemáticas
• Highlight.js para código com syntax highlighting combinado ao tema
• Servidor Express com listagem navegável dos HTML gerados
• Metadados de arquivos e pastas obtidos dos .md de origem
• node_modules excluído automaticamente das contagens e tamanhos
• Atualização automática em tempo real com watcher (somente .md) e hot-reload via SSE — o navegador recarrega automaticamente sem ação manual
• Logs no terminal com progresso amigável e URL de acesso
• Flag --clean para remover arquivos obsoletos antes da geração
• 9 temas visuais selecionáveis via --theme — aplicados tanto nas páginas de documento quanto no índice de arquivos
• Escala de fonte: botões A− / A+ em todas as páginas para aumentar ou diminuir o texto globalmente; preferência persistida em localStorage
• Modo Todos os Arquivos: botão que lista todos os documentos de todas as pastas em uma única tabela, com coluna indicando a pasta de origem de cada arquivo
• Busca: localiza documentos por nome ou conteúdo; exibe badges de correspondência e trecho do conteúdo encontrado; ativa automaticamente o modo Todos os Arquivos quando no índice raiz; quando dentro de uma pasta, limita os resultados àquela pasta e suas subpastas

Temas

Selecione um tema com --theme <nome>. O tema é aplicado tanto nas páginas de documento quanto no índice de arquivos.

| Tema | Estilo | |---|---| | default | Claro limpo — cinzas neutros, destaque índigo | | dark | Azul-cinza escuro — gradiente violeta/ciano | | github | Claro estilo GitHub — familiar e legível | | retro | Sépia quente, fontes serifadas, sensação de máquina de escrever | | dracula | Paleta Dracula clássica — roxo/rosa/ciano | | nord | Frio ártico — paleta azul-cinza suave | | catppuccin | Pastel Mocha — suave e amigável | | solarized | Solarized Dark — âmbar/verde em fundo azul-acinzentado | | corporate | Claro profissional — slate/azul |

Cada tema inclui folha de estilo do highlight.js combinada, tema do Mermaid e par de fontes Google Fonts.

html-gen --input docs/ --output html/ --theme dracula

Múltiplas pastas de entrada

Passe duas ou mais pastas em --input para unificá-las em um único site de documentação:

html-gen --input docs/ crm/ wiki/ --output html/

Entrada única (padrão): a saída espelha a estrutura da pasta de origem diretamente dentro de --output.

Múltiplas entradas: cada pasta de origem vira uma subpasta dentro de --output com o mesmo nome:

--input docs/ crm/  →  html/docs/…  +  html/crm/…

O índice exibe docs/ e crm/ como pastas de nível raiz. A busca e o Modo Todos os Arquivos cobrem todas elas. O watcher monitora cada pasta de forma independente e atualiza o navegador via hot-reload em qualquer mudança.

Funcionalidades de navegação

Escala de fonte

Todas as páginas possuem botões A− e A+ na barra superior, ao lado dos links Index e Topo. Clicar neles diminui ou aumenta o tamanho global do texto em seis etapas (80 % → 90 % → 100 % → 110 % → 120 % → 135 %). A escala escolhida é salva em localStorage e restaurada no próximo acesso — inclusive ao alternar entre o índice e páginas de documento.

Modo Todos os Arquivos

Clique em 📋 Todos os Arquivos na barra da listagem para ver todos os documentos gerados de todas as pastas em uma tabela plana. A coluna Pasta indica a pasta de origem de cada arquivo. Clique novamente no botão para voltar à navegação normal por pastas.

Busca

Digite um termo na barra de pesquisa e pressione Enter ou clique em 🔎 Buscar.

• A busca funciona sobre nomes de arquivos e conteúdo (indexado em memória a partir dos .md de origem).
• Os resultados exibem um badge indicando se a correspondência foi no nome, no conteúdo ou em ambos, além de um trecho do texto encontrado.
• Se você estiver no índice raiz, a busca ativa automaticamente o modo Todos os Arquivos para cobrir toda a documentação.
• Se você estiver dentro de uma pasta (ex.: /guias), os resultados ficam limitados àquela pasta e suas subpastas.
• O watcher mantém o índice de conteúdo atualizado: arquivos .md adicionados, modificados ou excluídos são refletidos na próxima busca sem reiniciar o servidor.
• Clique em ✖ Limpar para limpar a busca e retornar à visualização anterior.

Estrutura do projeto

bin/
  html-gen.js                # entrypoint CLI global
src/
  app/run.js                 # orquestração principal
  cli/parse-args.js          # parse e validação de argumentos
  config/
    runtime-config.js        # resolução de paths e defaults
    temp-output.js           # pasta temporária por SO
  conversion/
    discovery.js             # busca recursiva de markdown
    converter.js             # pipeline markdown -> html
  html/template.js           # template final da página html
  markdown/
    frontmatter.js           # parser de frontmatter com fallback
    renderer.js              # markdown-it + plugins
  server/
    directory-listing.js     # listagem html de arquivos gerados
    start-server.js          # inicialização do express
test/
  *.test.js                  # testes automatizados (node:test)
docs/
  teste-completo.md          # markdown completo para validar renderização

Desenvolvimento

Instalar dependências:

npm install

Executar testes:

npm test

Rodar localmente:

npm start -- --input docs --output docs-html --port 12334

Com Bun:

bun ./bin/html-gen.js --input docs --output docs-html

CI/CD no GitLab

O projeto inclui pipeline em .gitlab-ci.yml com dois estágios:

• test: executa npm test em branches e merge requests
• release: executa npm run release na branch main (semantic-release)

Para publicação automática no npm, configure no GitLab (CI/CD Variables):

• NPM_TOKEN: token do npm com permissão de publish
• GL_TOKEN: token de acesso ao GitLab (escopo api)

FAQ

1. O comando não encontrou arquivos markdown. O que fazer?

Verifique se a pasta informada em --input existe e contém arquivos .md.

2. Preciso informar sempre --output?

Não. Sem --output, a ferramenta cria uma pasta temporária automaticamente.

3. Posso usar em Node e Bun?

Sim. O pacote foi implementado em CommonJS com bibliotecas compatíveis com os dois runtimes.

4. A porta já está em uso. Como resolver?

Informe outra porta com --port, ou remova a opção para usar uma porta livre automaticamente.

5. A ferramenta observa alterações em tempo real?

Sim. Depois da publicação inicial, o watcher monitora mudanças em .md, reconverte automaticamente e exibe a URL novamente no terminal.

6. A contagem de arquivos parece errada numa pasta com scripts ou dependências. Por quê?

A ferramenta conta apenas arquivos .md e exclui automaticamente diretórios node_modules de todas as contagens e cálculos de tamanho.

7. Como garantir dados sempre frescos, sem HTML obsoleto?

Use --clean para esvaziar a pasta de saída antes de cada execução:

html-gen --input docs/ --output docs-html/ --clean

8. Como a busca conhece o conteúdo dos arquivos?

Ao iniciar, a ferramenta lê todos os arquivos .md de origem e cria um índice em memória. O watcher mantém esse índice atualizado: edições, novos arquivos e exclusões são refletidos imediatamente, sem reiniciar o servidor.

9. Como buscar apenas dentro de uma pasta específica?

Navegue até a pasta primeiro (ex.: abra http://localhost:PORTA/?path=guias) e use a barra de busca. Os resultados serão limitados àquela pasta e suas subpastas.

10. Como escolher um tema visual?

Use --theme <nome> ao iniciar. Exemplo: html-gen --input docs/ --theme dark. Veja a seção Temas para todas as opções disponíveis.

11. Posso servir múltiplas pastas de documentação ao mesmo tempo?

Sim. Passe todas as pastas em --input:

html-gen --input docs/ crm/ wiki/ --output html/

Cada pasta vira uma subpasta de nível raiz na saída, e o índice lista todas juntas.

12. Como funciona a escala de fonte?

Todas as páginas possuem botões A− e A+ na barra superior. Clicar neles alterna o tamanho do texto entre seis etapas (80 % a 135 %). A preferência fica salva em localStorage e é restaurada automaticamente no próximo acesso — inclusive ao alternar entre o índice e as páginas de documentos.

Documentação adicional

• API detalhada: docs/API.md
• Guia de contribuição: CONTRIBUTING.md
• Histórico de mudanças: CHANGELOG.md
• Publicação no npm: docs/npm-publish-guide.md

Licença

ISC