Skip to content

Commit 432f4fd

Browse files
committed
docs: add guide on contributing to docs
1 parent 03b7760 commit 432f4fd

File tree

1 file changed

+30
-0
lines changed

1 file changed

+30
-0
lines changed

docs/src/6-contributing.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,21 +160,51 @@ Publishing a new release of the CLI and lib requires these steps:
160160
4. CI will build the binaries and upload them to the GitHub release and the NPM registry. It will also publish the Rust
161161
crates to crates.io.
162162

163+
## Developing Documentation
164+
165+
Our current static site generator for documentation is [`mdBook`][mdBook], with a little bit of custom JavaScript to handle
166+
the playground page. Most of the documentation is written in Markdown, including this file! You can find these files
167+
at [`docs/src`][docs src]. The playground code can be found in [`docs/assets/js/playground.js`][playground], and its corresponding
168+
css at [`docs/assets/css/playground.css`][playground css]. To run and iterate on the docs locally, the
169+
[`mdbook`][mdbook cli] CLI tool is required, which can be installed with `cargo install mdbook`. Once you've installed it,
170+
you can run the following command to start a local server:
171+
172+
```sh
173+
cd docs
174+
mdbook serve --open
175+
```
176+
177+
`mdbook` has a live-reload feature, so any changes you make to the markdown files will be reflected in the browser after
178+
a short delay. Once you've made a change that you're happy with, you can submit a PR with your changes.
179+
180+
The playground page is a little more complicated, but if you know some basic JavaScript and CSS you should be able to make
181+
changes. The editor of choice we use for the playground is [CodeMirror][codemirror], and the tree-sitter module is fetched
182+
from [here][js url]. This, along with the wasm module and wasm parsers, live in
183+
the [.github.io repo][gh.io repo].
184+
163185
[cli crate]: https://crates.io/crates/tree-sitter-cli
164186
[cli package]: https://www.npmjs.com/package/tree-sitter-cli
187+
[codemirror]: https://codemirror.net
165188
[covenant]: https://www.contributor-covenant.org/version/1/4/code-of-conduct
166189
[crates]: https://crates.io
167190
[docker]: https://www.docker.com
191+
[docs src]: https://github.com/tree-sitter/tree-sitter/tree/master/docs/src
168192
[emscripten]: https://emscripten.org
193+
[gh.io repo]: https://github.com/tree-sitter/tree-sitter.github.io
169194
[go.dev]: https://pkg.go.dev
170195
[go package]: https://pkg.go.dev/github.com/tree-sitter/go-tree-sitter
171196
[go ts]: https://github.com/tree-sitter/go-tree-sitter
172197
[highlight crate]: https://crates.io/crates/tree-sitter-highlight
198+
[js url]: https://tree-sitter.github.io/tree-sitter.js
173199
[lib crate]: https://crates.io/crates/tree-sitter
200+
[mdBook]: https://rust-lang.github.io/mdBook
201+
[mdbook cli]: https://rust-lang.github.io/mdBook/guide/installation.html
174202
[node package]: https://www.npmjs.com/package/tree-sitter
175203
[node ts]: https://github.com/tree-sitter/node-tree-sitter
176204
[npm version]: https://docs.npmjs.com/cli/version
177205
[npmjs]: https://npmjs.com
206+
[playground]: https://github.com/tree-sitter/tree-sitter/blob/master/docs/assets/js/playground.js
207+
[playground css]: https://github.com/tree-sitter/tree-sitter/blob/master/docs/assets/css/playground.css
178208
[podman]: https://podman.io
179209
[py package]: https://pypi.org/project/tree-sitter
180210
[py ts]: https://github.com/tree-sitter/py-tree-sitter

0 commit comments

Comments
 (0)