Thanks for taking the time to contribute! 🎉 MarkSight is an open source markdown editor, and contributions of every size are welcome, from fixing a typo to building a new feature.
This guide explains how to get set up and how to land a change. If anything here is unclear or out of date, that's a bug too: open an issue or PR.
- Ways to contribute
- Getting started
- Development workflow
- Project structure
- Coding guidelines
- Commit messages
- Opening a pull request
- Reporting bugs & requesting features
- Code of Conduct
You don't have to write code to help:
- 🐛 Report a bug — open a bug report.
- 💡 Suggest a feature — open a feature request.
- 📖 Improve the docs — fix a typo, clarify a step, add an example.
- 🧹 Pick up an issue — look for issues labelled
good first issueorhelp wanted.
If you're planning a larger change, please open an issue first so we can agree on the approach before you invest time in it.
Prerequisites: Node.js 22 or newer (the version
pinned in .nvmrc and the one CI runs) and npm (bundled with Node).
# 1. Fork the repo on GitHub, then clone your fork
git clone https://github.com/<your-username>/MarkSight.git
cd MarkSight
# 2. Install dependencies
npm install
# 3. Start the dev server at http://localhost:3000
npm run devThat's it. Edit a file under src/ and the page hot-reloads.
| Command | What it does |
|---|---|
npm run dev |
Start the dev server with Turbopack |
npm run build |
Production build |
npm run start |
Serve the production build |
npm run lint |
Run ESLint |
npm run typecheck |
Type-check with tsc --noEmit (takes seconds) |
npm test |
Run the unit tests (Vitest) |
Brand assets (icons, social images) are generated from inline SVG:
node scripts/generate-assets.mjspackage.json has an overrides block. JSON can't hold comments, so the
reasons live here:
| Override | Why it's there | When it can go |
|---|---|---|
prismjs |
react-syntax-highlighter pulls in an older Prism through refractor that has a known DOM clobbering advisory. The override forces the patched 1.30 line. |
Once react-syntax-highlighter depends on prismjs >= 1.30 by itself. |
postcss |
Next.js pins an exact, older postcss that has an XSS advisory in its CSS stringifier. The override dedupes everything onto a patched 8.5 release. |
Once Next.js ships with postcss >= 8.5.10 and npm ls postcss is single. |
If you remove one, run npm ls <package> --all and npm audit to confirm
nothing vulnerable comes back.
-
Create a branch off
mainwith a descriptive, prefixed name:git checkout -b fix/preview-scroll-jump # or feat/…, docs/…, perf/…, refactor/…, chore/… -
Make your change in small, focused commits.
-
Before pushing, make sure the project still lints, tests, and builds cleanly:
npm run lint npm run typecheck npm test npm run build -
Push to your fork and open a pull request.
src/
├── app/ # App Router entry (layout, page, metadata, route assets)
│ └── api/ # route handlers (MCP server, AI skill improvement)
├── components/ # UI components (editor, preview, toolbar, sidebar, …)
│ └── ui/ # shadcn/ui primitives — avoid hand-editing; re-add via the CLI
├── contexts/ # React context providers
├── hooks/ # custom hooks
├── lib/ # utilities (slugify, local storage, syntax highlighter, …)
└── proxy.ts # security headers / CSP
Tests live next to the code (src/**/__tests__/ or a sibling *.test.ts) and
run with Vitest. The file extension picks the
environment:
*.test.tsruns in plain Node. Use it for pure logic (most ofsrc/lib).*.test.tsxruns in jsdom with Testing Library. Use it for hooks and components.src/lib/__tests__/use-debounced-value.test.tsxis a good one to copy from.
- Language: TypeScript and React 19 (App Router). Prefer Server Components;
add
"use client"only when a component needs interactivity or browser APIs. - Styling: Tailwind CSS v4 utility classes and the
shadcn/ui primitives in
src/components/ui. Add new primitives with the shadcn CLI rather than copying files by hand. - Formatting: an
.editorconfigdefines the basics (2-space indent, LF line endings). Keep the diff small: match the style of the surrounding code and let ESLint guide you. - Linting:
npm run lintmust pass with no errors. Fix warnings you introduce. - Accessibility: keep it keyboard-navigable and screen-reader friendly. Label interactive controls, preserve focus order, and don't remove focus outlines.
- Dependencies: avoid adding a dependency for something small. If a new package is genuinely needed, mention why in the PR.
We follow Conventional Commits. Start each message with a type, then a short imperative summary:
feat: add word-count to the status bar
fix: stop the preview pane jumping on first render
docs: document the asset-generation script
perf: shrink the client bundle
Common types: feat, fix, docs, style, refactor, perf, test,
chore, build, security.
- Target the
mainbranch. - Fill in the PR template: describe what changed and why, and link any
related issue (e.g.
Closes #12). - Add before/after screenshots or a short clip for any visible UI change.
- If your change is user-facing, add a line to the Unreleased section of
CHANGELOG.md. - Confirm
npm run lint,npm test, andnpm run buildpass locally. - Keep the PR focused. One logical change per PR is much easier to review.
A maintainer aims to give every pull request a first response within a few days. They'll review your PR, may suggest changes, and will merge it once it's ready. Don't be discouraged by review feedback; it's how we keep the codebase healthy.
Use the issue templates so we get the details we need:
- Bugs: include steps to reproduce, what you expected, what happened, and your browser/OS. A screenshot or console error helps a lot.
- Features: describe the problem you're trying to solve, not just the solution. It helps us find the best fit for the project.
Please search existing issues first to avoid duplicates.
This project is governed by our Code of Conduct. By participating, you're expected to uphold it. Please report unacceptable behavior to the maintainer.
Happy hacking, and thank you for helping make MarkSight better! 💛