mdo

English · Português

Note

This is a vibe-coded project: it is built experimentally with AI-assisted coding and human direction/review.

English

mdo is a disposable Markdown reader for the terminal and browser, written in Go.

Development usage

go run . README.md

The browser controls use bundled Web Awesome components. Their generated assets are checked in, so normal Go builds do not need Node.js. To rebuild those assets after changing web-ui/components.js or its dependencies:

cd web-ui
npm ci
npm run build

mdo validates the file, chooses a free local port, opens the browser, and shuts down the server after the page and Mermaid diagrams have rendered. The already loaded page remains available, but it cannot be reloaded after the server stops.

Only files with the exact .md extension are accepted.

Choose a default theme

Run mdo --theme in an interactive terminal to choose a theme without opening the browser. The choice is saved in ~/.config/mdo/config.json and used the next time you open a document. The menu includes Default, Default light, all four Catppuccin flavors, Nord, all four Tokyo Night styles, Dracula Classic, and Alucard Classic. Without a saved choice, the reader follows your system's light or dark preference.

You can also change the theme in the browser. That change affects only the current page; a dismissible toast reminds you to run mdo --theme to change the default. The dropdown, notification, and buttons work offline.

Share temporarily over the internet

Use --live (or -l) to create a temporary public link through ngrok:

mdo --live README.md
# or
mdo -l README.md

First, install the ngrok Agent CLI, create or sign in to your account, and configure your authtoken once:

ngrok config add-authtoken <YOUR_TOKEN>

mdo prints the HTTPS link to share and keeps the server and tunnel running until you press Ctrl+C. This mode uses only the automatically assigned free development domain: it does not configure a reserved domain or paid features. See the ngrok quickstart for installation instructions and your token. Without -l/--live, mdo continues to run only on localhost and does not look for or require ngrok.

Features

• CommonMark and GitHub Flavored Markdown
• tables, task lists, autolinks, and strikethrough text
• nested task lists with completed labels struck through
• GitHub-style alerts and Obsidian-style callouts, including foldable titles
• footnotes and definition lists
• syntax highlighting
• table of contents and heading links
• code block copying
• offline Mermaid diagrams
• images relative to the Markdown file
• print or save as PDF using your browser

PDF export

After the document loads, click Print / PDF and choose Save as PDF in your browser's print dialog. Export works after mdo exits, without a separate Chrome installation. The button prepares diagrams with a light print palette and restores their interactive view after printing or cancellation. Paper size, margins, backgrounds, and heading bookmarks depend on the browser and its print settings. No PDF is generated during startup.

Install from a release

The installers download the package for the current platform from the latest GitHub Release and install the executable on the system.

Install with a package manager

Once published to npm, install mdo globally with one of these commands:

npm install --global @egomes.dev/mdo
pnpm add --global @egomes.dev/mdo
yarn global add @egomes.dev/mdo # Yarn Classic

The npm package selects the native binary for your operating system and CPU. Check for a newer release or install it with:

mdo update --check
mdo update

mdo update uses the package manager that originally installed the command.

Linux

chmod +x ./install-linux.sh
./install-linux.sh

Installs mdo in /usr/local/bin/mdo.

macOS

chmod +x ./install-mac.sh
./install-mac.sh

Installs mdo in /usr/local/bin/mdo.

Windows

Open PowerShell as Run as administrator, go to the directory that contains install-windows.ps1, then run both commands in the same window:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
.\install-windows.ps1

The script-policy change applies only to the current session and is discarded when the PowerShell window closes.

The installer places mdo.exe in $env:ProgramFiles\mdo (usually C:\Program Files\mdo) and adds that directory to the system PATH for all users. Administrator rights are required to write to this location and update the system environment variable.

The installer also updates the PATH in the current PowerShell session, so the command is immediately available:

Get-Command mdo
mdo .\README.md

Other terminals already open must be closed and reopened. If you use Windows Terminal, close all its windows before opening it again.

Install globally with Go

go install github.com/egomes/mdo@latest

The executable is installed in GOBIN or, when it is not defined, in $(go env GOPATH)/bin. That directory must be in your PATH.

Tests

go test ./...

Run the race detector with:

go test -race ./...

flowchart LR
    A[Markdown] --> B[mdo]
    B --> C[Browser]
    C --> D[Server stops]

Loading

---

Português

mdo é um leitor descartável de Markdown para o terminal e navegador, escrito em Go.

Uso durante o desenvolvimento

go run . README.md

O mdo valida o arquivo, escolhe uma porta local livre, abre o navegador e encerra o servidor assim que a página e os diagramas Mermaid terminam de renderizar. A página já carregada continua disponível, mas não pode ser recarregada depois que o servidor encerra.

Somente arquivos com extensão exata .md são aceitos.

Escolher o tema padrão

Execute mdo --theme em um terminal interativo para escolher um tema sem abrir o navegador. A escolha é salva em ~/.config/mdo/config.json e usada ao abrir outro documento. O menu inclui Default, Default light, as quatro variantes Catppuccin, Nord, os quatro estilos Tokyo Night, Dracula Classic e Alucard Classic. Sem uma escolha salva, o leitor segue a preferência de cores do sistema.

Também é possível trocar o tema no navegador. Essa troca vale apenas para a página atual; uma notificação que pode ser fechada lembra você de usar mdo --theme para mudar o padrão. O seletor, a notificação e os botões funcionam offline.

Compartilhar temporariamente pela internet

Use --live (ou -l) para criar um link público temporário com ngrok:

mdo --live README.md
# ou
mdo -l README.md

Antes disso, instale o ngrok Agent CLI, crie ou acesse sua conta e configure o authtoken uma vez:

ngrok config add-authtoken <YOUR_TOKEN>

O mdo imprime o link HTTPS que deve ser compartilhado e mantém o servidor e o túnel ativos até você pressionar Ctrl+C. O modo usa apenas o domínio de desenvolvimento automático do plano gratuito: não configura domínio reservado nem recursos pagos. Consulte o quickstart do ngrok para obter o token e instruções de instalação. Sem -l/--live, o mdo continua funcionando somente em localhost e não procura nem exige o ngrok.

Recursos

• CommonMark e GitHub Flavored Markdown
• tabelas, listas de tarefas, autolinks e texto tachado
• notas de rodapé e listas de definição
• syntax highlighting
• sumário e links de títulos
• cópia de blocos de código
• diagramas Mermaid offline
• imagens relativas ao arquivo Markdown
• impressão ou exportação em PDF pelo navegador

Exportação de PDF

Depois que o documento carregar, clique em Print / PDF e escolha Salvar como PDF no diálogo de impressão do navegador. A exportação funciona após o mdo encerrar, sem uma instalação separada do Chrome. O botão prepara os diagramas com uma paleta clara e restaura a visualização interativa após imprimir ou cancelar. Papel, margens, fundos e marcadores de títulos dependem do navegador e das configurações de impressão. Nenhum PDF é gerado durante a abertura.

Instalação por release

Os instaladores baixam o pacote adequado dos assets da última release do GitHub e instalam o executável no sistema.

Instalação com gerenciador de pacotes

Depois da publicação no npm, instale o mdo globalmente com um destes comandos:

npm install --global @egomes.dev/mdo
pnpm add --global @egomes.dev/mdo
yarn global add @egomes.dev/mdo # Yarn Classic

O pacote npm seleciona o binário nativo para seu sistema operacional e CPU. Verifique se há uma release nova ou instale-a com:

mdo update --check
mdo update

mdo update usa o gerenciador de pacotes que instalou o comando originalmente.

Linux

chmod +x ./install-linux.sh
./install-linux.sh

Instala o mdo em /usr/local/bin/mdo.

macOS

chmod +x ./install-mac.sh
./install-mac.sh

Instala o mdo em /usr/local/bin/mdo.

Windows

Abra o PowerShell com Executar como administrador, acesse a pasta que contém install-windows.ps1 e execute os dois comandos na mesma janela:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
.\install-windows.ps1

A liberação de scripts acima vale somente para essa sessão do PowerShell e termina quando a janela é fechada.

O instalador coloca mdo.exe em $env:ProgramFiles\mdo (normalmente C:\Program Files\mdo) e adiciona esse diretório ao PATH do sistema para todos os usuários. A instalação exige administrador para gravar nesse diretório e alterar a variável de ambiente do sistema.

O instalador também atualiza o PATH da sessão atual do PowerShell. O comando fica disponível imediatamente:

Get-Command mdo
mdo .\README.md

Outros terminais que já estavam abertos precisam ser fechados e reabertos. Se estiver usando o Windows Terminal, feche todas as janelas do aplicativo e abra-o novamente.

Instalação global com Go

go install github.com/egomes/mdo@latest

O executável será instalado em GOBIN ou, quando essa variável não estiver definida, em $(go env GOPATH)/bin. Esse diretório precisa estar no PATH.

Testes

go test ./...

Para incluir o detector de condições de corrida:

go test -race ./...

flowchart LR
    A[Markdown] --> B[mdo]
    B --> C[Navegador]
    C --> D[Servidor encerrado]

Loading

Callouts / Blocos de destaque

> [!NOTE]+ TODO
> Migrate dotfiles tasks from Notion to here?

> [!WARNING]- Details / Detalhes
> Expand to read / Expanda para ler.

Supported syntax follows Obsidian callouts: + starts expanded, - starts collapsed, and no sign creates a static callout. Titles support inline Markdown. Callouts expand for printing and return to their previous state afterwards. Task checkboxes are read-only; the source file is not edited.

A sintaxe segue os callouts do Obsidian: + começa aberto, - começa recolhido e sem sinal cria um bloco fixo. Os títulos aceitam Markdown inline. Na impressão, os blocos são expandidos e depois retornam ao estado anterior. As caixas de tarefas são apenas para leitura; o arquivo original não é alterado.