Skip to content

Contributing.md

Latest commit

 

History

History
111 lines (81 loc) · 3.73 KB

Contributing.md

File metadata and controls

111 lines (81 loc) · 3.73 KB
Raw

Contributing

Thanks for helping improve Markdown Viewer. Contributions can include bug reports, documentation fixes, renderer improvements, accessibility work, desktop packaging, deployment fixes, tests, and translations.

Before Changing Code

  • Read Features to understand current user-facing behavior and privacy boundaries.
  • Check CHANGELOG.md for historical context.
  • Keep changes scoped to the feature or bug you are working on.
  • Do not remove user-facing behavior from docs unless the code no longer implements it.

Local Web Development

The root app has no required build step.

git clone https://github.com/ThisIs-Developer/Markdown-Viewer.git
cd Markdown-Viewer
python -m http.server 8080

Open http://localhost:8080.

Use a local HTTP server, not file://, because Web Workers and Service Workers depend on browser origin rules.

Desktop Development

cd desktop-app
npm install
npm run setup
npm run dev

Run npm run setup or node prepare.js after changing root assets that the desktop build consumes. Desktop generated resource files should match the root app after preparation.

Cloudflare Features

Stored Share Snapshot requires SHARE_KV. Live Share requires LIVE_ROOMS and the LiveRoom Durable Object.

When changing share or live behavior, update:

  • script.js
  • functions/api/share/[[id]].js
  • functions/live-room/[[room]].js
  • workers/live-room-worker.js
  • wiki/Features.md
  • wiki/Live-Share-Cloudflare.md
  • wiki/FAQ.md

Code Style

  • Use plain JavaScript, HTML, and CSS unless a focused dependency is already part of the app.
  • Keep browser compatibility in mind.
  • Keep expensive work off the hot typing path.
  • Sanitize rendered HTML before insertion.
  • Preserve accessibility attributes and keyboard behavior.
  • Keep desktop native API permissions as narrow as possible.
  • Use clear names and comments only where they explain non-obvious logic.

Documentation Rules

  • Update existing wiki pages instead of creating new pages for small topics.
  • Document user-facing behavior, limits, data handling, and privacy implications.
  • Keep wording simple and direct.
  • If a feature sends data to a service, say so.
  • If a feature is local-only, say where it is stored.
  • Keep README summaries aligned with the wiki.

Commit Messages

Conventional commit style is preferred:

feat(editor): add table alignment option
fix(pdf): prevent blank trailing raster page
docs(wiki): clarify live share storage behavior
perf(render): reduce line gutter layout work

Useful types include feat, fix, docs, style, refactor, perf, test, and chore.

Pull Requests

A good PR includes:

  • What changed.
  • Why it changed.
  • How it was tested.
  • Screenshots or recordings for UI changes.
  • Privacy/storage notes for share, import, live, renderer, or desktop changes.
  • Documentation updates when behavior changes.

Security Reports

Please do not open public issues for vulnerabilities. Use GitHub Security Advisories if available or contact the maintainers privately with a minimal reproduction and impact notes.

Repository Map

Path Purpose
index.html App shell, toolbar, modals, default content, CDN tags.
script.js Main application logic.
preview-worker.js Worker Markdown rendering path.
styles.css Layout, themes, renderer styles, modals, responsive UI.
sw.js PWA/service-worker cache behavior.
functions/api/share/[[id]].js Stored Share Snapshot API.
functions/live-room/[[room]].js Cloudflare Pages Live Share WebSocket entry.
workers/live-room-worker.js Live Share Durable Object relay.
desktop-app/ Neutralino desktop wrapper and build preparation.
wiki/ Documentation source pages.