Đọc Markdown trong browser với ak:markdown-novel-viewer

Dùng ak:markdown-novel-viewer để đọc Markdown file dài trong browser interface tập trung kiểu sách hoặc browse một directory document. Skill khởi động HTTP server bằng Node.js, render Markdown theo request, resolve local image và thêm navigation, reading progress, syntax highlighting cùng Mermaid diagram.

Chọn ak:markdown-novel-viewer để đọc

Dùng ak:markdown-novel-viewer khi

• Bạn muốn view ít xao nhãng cho RFC, runbook, design document, report, specification, plan hoặc long-form manuscript.
• Bạn muốn browse document directory và theo Markdown link trực quan.
• Bạn muốn heading, table of contents, code highlighting, theme và font control, reading progress hay previous và next navigation riêng cho plan.
• Bạn muốn Mermaid block được render trong browser và có thể cho phép CDN request bắt buộc.

Chọn workflow khác khi

• Bạn cần self-contained HTML file thay vì server đang chạy. Dùng HTML generation mode trong ak:preview.
• Bạn cần edit hoặc validate Markdown content. Dùng ak:docs hay authoring Skill phù hợp trước khi preview.
• Bạn cần Mermaid source artifact được xác minh độc lập với viewer này. Dùng ak:mermaidjs-v11.
• Content không đáng tin hoặc nhạy cảm và không thể render an toàn thành HTML hay expose qua local HTTP process.

Chuẩn bị Node, source và browser access

Trước khi bắt đầu:

• Hoàn tất Onboarding, rồi xác nhận Engineer Kit được cài cho runtime và scope hiện tại.
• Cung cấp một Markdown file hoặc một directory. Relative path resolve từ current working directory.
• Chuẩn bị Node.js cùng npm dependency của Skill. Package khai báo marked, highlight.js và gray-matter; khi chưa cài, Markdown rendering trả HTTP 500.
• Duyệt dependency installation riêng. Chạy npm install trong Skill directory sẽ ghi dependency artifact và dùng package registry.
• Quyết định browser có được truy cập Google Fonts, cdnjs và jsDelivr không. Rendered page tải font, Highlight.js theme CSS cùng Mermaid 11 từ các public CDN đó.

Input được khai báo là [file-or-directory]. Hãy nêu path, host, port policy, browser-opening preference, background hoặc foreground lifecycle, network access và stop behavior khi các ranh giới đó quan trọng.

Khởi động reader chỉ local

/ak:markdown-novel-viewer ./docs/system-design.md "Serve on localhost, use the first available port from 3456, do not bind to the network, do not open a browser automatically, report the URL and PID state, and stop the server when I finish reviewing."

/ak:markdown-novel-viewer ./docs/system-design.md "Serve on localhost, use the first available port from 3456, do not bind to the network, do not open a browser automatically, report the URL and PID state, and stop the server when I finish reviewing."

$ak:markdown-novel-viewer ./docs/system-design.md "Serve on localhost, use the first available port from 3456, do not bind to the network, do not open a browser automatically, report the URL and PID state, and stop the server when I finish reviewing."

Integration được document trong Skill cũng chỉ tới ak:preview để truy cập nhanh. Dùng invocation viewer riêng khi bạn muốn server lifecycle và security boundary của nó là chủ thể rõ ràng trong request.

Hiểu server control

Để dùng script trực tiếp, chạy entry point node scripts/server.cjs đi kèm trong environment nơi dependency resolve. Attached start thành công báo URL, path, port, host cùng file hoặc directory mode. Nhánh background, foreground, child và command-integrated phát JSON; network URL được thêm khi bind 0.0.0.0 và tìm thấy local IPv4 address.

Quan sát các giai đoạn reader

1. Skill resolve input. Skill kiểm tra current working directory, xác định file hay directory mode và từ chối path thiếu hoặc không hợp lệ.
2. Skill chuẩn bị runtime. npm module bắt buộc phải resolve trước lần Markdown render đầu tiên.
3. Skill chọn port khả dụng. Port được yêu cầu được dùng khi rảnh hoặc port khả dụng tiếp theo được báo.
4. Skill khởi động HTTP server. Asset, current working directory và target directory trở thành allowed file root cho process đó.
5. Skill render document hoặc listing. Markdown frontmatter, heading, local image, code block, plan navigation và directory entry trở thành HTML.
6. Browser tải enhancement. Reader JavaScript local thêm theme, font, sidebar, keyboard, mobile và progress behavior; external CDN resource thêm font, highlight theme và Mermaid.
7. Run tiếp tục active đến khi dừng. PID file hỗ trợ discovery và shutdown; final report nên xác nhận process cùng port đã không còn.

Đọc Mermaid block và plan document

Fenced block mermaid được escape trên server, rồi render trong browser bằng Mermaid 11 từ jsDelivr. Diagram theo reader theme light hoặc dark, có thể mở rộng theo main content width và được render lại sau khi đổi theme. Lỗi render hiển thị inline cùng source preview.

Đây là rendering evidence, không phải guarantee validation đầy đủ. Page phải truy cập được CDN, browser phải thực thi module và source phải hợp lệ với release Mermaid 11 được tải. Reader khởi tạo Mermaid bằng securityLevel: 'loose'; không dùng diagram source không đáng tin.

Plan navigation được suy ra từ plan file và phase table được nhận diện. Khi document không được phát hiện là plan, nó vẫn có heading cùng table of contents chuẩn nhưng có thể không có phase badge và previous hay next navigation. Reader preference cùng accordion state được lưu trong localStorage của browser.

Kiểm soát HTTP và content boundary

• Markdown renderer không thêm sanitization layer cho raw HTML. Hãy coi Markdown, embedded HTML, link, filename và Mermaid source là trusted input trước khi mở page.
• Directory mode liệt kê non-hidden file thuộc nhiều loại và link chúng qua local file route. Không serve project directory rộng chứa secret, private report, source map, export hoặc credential.
• Local image được resolve theo Markdown file và serve qua cùng process. Remote image URL vẫn là remote và có thể lộ browser network metadata cho host đó.
• Reader liên hệ public font và script hoặc stylesheet CDN trừ khi browser chặn. Đọc offline có thể mất font, highlight theme và Mermaid rendering dù plain Markdown vẫn load.
• Browser launch dùng opener của operating system. Giữ --no-open khi session chỉ nên báo URL hoặc khi mở UI chưa được cấp quyền.
• Stop bằng --stop nhắm tới mọi viewer PID được phát hiện. Kiểm tra active instance trước nếu user hoặc task khác có thể đang chạy reader.

Xác minh live output

Kết quả đầy đủ nên gồm:

• Resolved source path, file hay directory mode, bind host, actual port, local URL, optional network URL, process mode và PID-file state.
• Xác nhận dependency đã resolve và installation có thay đổi Skill directory hay không.
• HTTP result cho target page cùng local asset, cộng browser confirmation cho heading, table, code, image, navigation, theme, keyboard và mobile behavior được yêu cầu.
• Mermaid source cùng render status cho mọi diagram, giữ CDN hoặc syntax error tách biệt với server-rendering failure.
• Network request tới font hoặc CDN cùng directory chính xác khả dụng qua browse hoặc file route.
• Shutdown evidence cho thấy server process đã kết thúc, port đã đóng và stale PID file được xử lý.

Package chứa unit-style và server helper cho port, PID state, MIME type, path check, Markdown image resolution, heading, table of contents cùng plan navigation. Các test đó không được chạy trong batch tài liệu này. Hai release stable và beta được ghim chứa cùng viewer file.

Khắc phục sự cố và hiểu giới hạn

Dùng ak:preview cho preview workflow rộng hơn hoặc ak:mermaidjs-v11 để author và validate diagram source.