This is an interactive reStructuredText renderer working entirely in the browser, allowing anyone to try out the rST syntax and see how it renders, without needing to set up a server or install any software.
Try it out at https://waldyrious.github.io/rst-playground.
| Screenshot |
|---|
 |
The tool is a simple HTML page with a <textarea> and an <iframe> element side-by-side.
It uses Pyodide to call docutils
to convert plain-text rST-formatted content into HTML-based rich-text.
The following table summarizes how the repository is organized.
| Category | File/directory | Purpose |
|---|---|---|
| Core application files | 📄 index.xhtml |
Main HTML page containing the playground interface |
| Core application files | 📜 script.js |
JavaScript to convert rST→HTML using Pyodide |
| Core application files | 🎨 css/ |
Directory with local and upstream CSS stylesheets |
| ─── ⋄ ─── | ─── ⋄ ─── | ─── ⋄ ─── |
| Docs & metadata | 📖 README.md |
Project documentation (this file) |
| Docs & metadata | 🖼️ screenshot.png |
Screenshot of the playground |
| Docs & metadata | ⚖️ LICENSE.md |
ISC license text |
| ─── ⋄ ─── | ─── ⋄ ─── | ─── ⋄ ─── |
| Config & automation | 🧹 .prettierrc.toml |
Code formatting configuration for Prettier |
| Config & automation | ⚙️ .github/workflows/ |
GitHub Actions workflows for automated checks |
| Config & automation | 🔗 .gitmodules |
Git submodule configuration |
| Config & automation | 🔄 .renovaterc.json |
Automated updates for submodules and CDN URLs |
TL;DR: This project was triggered by the two well-known reStructuredText playgrounds — rst.ninjs.org [src] and livesphinx.herokuapp.com [src], a fork of the former — having stopped working as of December 2022, and because I am more used to markdown and too lazy to learn rST properly, so I find myself often needing such a playground where I can try out the syntax and see how it renders. (Also because I've been curious about Pyodide for a while, so it was an opportunity to give it a try.)
The original rST parser was created as part of the
Docutils project,
which remains the authoritative source of the spec
and the most complete implementation.
Indeed, the two defunct browser-based rST playgrounds mentioned above
called back to a server-side renderer in Python, running Docutils code.
There's also a relatively obscure browser-based playground
called rst-live-preview,
which relies on a Python CLI tool called
rst2html5
(not Docutils' rst2html).
To prevent the fate of the previous playgrounds, I wanted to focus on an alternative that would be extremely easy to host online — essentially, a fully client-side, static website, hostable in any free service like GitHub Pages or Neocities, without requiring a backend server component. And for that, I needed to run the rST→HTML conversion in JavaScript.
While there are implementations of rST parsers in various programming languages, I found no comprehensive and actively developed pure-JavaScript implementation. There is docutils-js, an attempt to port Docutils to JavaScript, but it's incomplete, and appears to be abandoned. There's also restructured, which is a similar project, and even has an online demo! But unfortunately it too is incomplete and unmaintained.
Faced with the challenges of maintaining a full rST parser in JavaScript,
I figured that perhaps Pyodide could be used
to run the Python-based rst2html directly the in the browser.
Pyodide even has the relevant packages
(docutils and pygments)
to enable this. Hence, this project was born.
This is a collaborative project, and contributions are welcome! Check the open issues for planned improvements. You can share feedback by opening new issues or commenting on existing ones. If you want to contribute more directly, feel free to fork the repository and submit pull requests.
This project is meant to be straightforward, lightweight, and easy to hack. If you're planning to submit changes, please keep the following principles in mind:
- Simple web page. The playground must remain fully functional as a plain HTML file loaded directly into the browser. No backend, no build steps, no need to run a local server.
- Straightforward, readable code. The code should be easy to follow for someone with basic programming knowledge, without requiring familiarity with modern tooling or trends. Avoid clever tricks, terse syntax or layered abstractions.
- Helpful documentation. Include comments that explain how and why things work, not just what they do. Aim to help the next person understand the reasoning behind the implementation.
- Single purpose. The tool is meant to be a simple and accurate rST renderer — not a full-fledged editor, linter, etc. Following the Unix principle, it should resist feature creep and avoid adding features beyond this core purpose.
The goal is a clean, maintainable codebase that’s easy to dive into and tweak. Any contributions that adhere to this philosophy are most welcome!
This project is hosted on GitHub, so you can contribute by forking the repository and submitting pull requests (PRs) with your changes. Simple changes like typos or minor improvements can be done directly in the GitHub web interface, but for more substantial changes, it's best to clone your fork of the repository and work locally:
git clone --recurse-submodules https://github.com/<your-username>/rst-playgroundThen, simply open the index.xhtml file in your browser.
There's no need to install anything, run a build step, or set up a local server.
Any edits you make in the HTML, CSS and JavaScript files will be applied by refreshing the page in the browser.
When you open a pull request, you can provide a live preview of your edited version
by setting up your GitHub fork to publish the branch where you are working using GitHub Pages.
Then, your version of the tool will be available at https://<your-username>.github.io/rst-playground/.
Code formatting is automatically checked on all pull requests using Prettier. If you would like to check the syntax of new code locally before submitting a PR, make sure you have Node.js installed, and run the same command defined in the workflow:
npx prettier --check . '!css/downstyler'Besides Prettier's default configuration, the .prettierrc.toml file lists additional rules used in this project.
This project is licensed under the ISC License.
