Skip to content

waldyrious/rst-playground

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

57 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

rst-playground

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.

How it works

The tool is a simple HTML page with a <textarea> and an <output> element side-by-side. It uses Pyodide to call docutils to convert plain-text rST-formatted content into HTML-based rich-text.

Motivation

This project was triggered by the two previous reStructuredText playgrounds (http://rst.ninjs.org and https://livesphinx.herokuapp.com) 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.)

Historical context

Contributing

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.

Development principles

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!

Development workflow

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 https://github.com/<your-username>/rst-playground

Then, 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 npx prettier . --check (you can use --write instead of --check to automatically format the code). Besides Prettier's default configuration, the .prettierrc.toml file lists additional rules used in this project.

License

This project is licensed under the ISC License.

About

Browser-based reStructuredText playground, built on Pyodide and docutils.

Topics

Resources

License

Stars

Watchers

Forks

Contributors 4

  •  
  •  
  •  
  •