ColorAide's documentation is rendered with Python Markdown and Pymdown Extensions. The color notebook implements a dynamic, live environment allowing for on the fly page rendering and interactive Python code examples with beautiful visualization of color. This is accomplished by using Pyodide to execute the required Python modules to render the desired pages.
Though Pyodide is used to run the Python code, the actual code is handled special so that we can intercept color objects at various times and translate them to color swatches and gradients. Because of this, asynchrounous code is not really handled due to the complications of us parsing the code within a Pyodide environment. There is also some additional overhead due to our process coupled with performance hits due to running in a browser, so speed within these "playgrounds" should not be indicative of actual performance, but in most cases is plenty fast to quickly visualize the features in Coloraide and the color concepts.
Pages can contain most Markdown but also special code blocks called playgrounds. These playgrounds are simple fenced code blocks that allow for a user to input and execute Python code. Each playground exposes access to ColorAide allowing for sandboxes to explore all the features of ColorAide. Additionally, the playgrounds will search for color objects, interpolation objects, and color strings and will render them as color previews.
To create a playground, simply create a normal Python fenced code block, but add the option play.
```py play
print("Hello world!")
```/// html | div.result
print("Hello world!")///
Each playground will have an Edit button that allows for live editing and a Share button that will generate shareable
URLs that can be loaded up dynamically in ColorAide's Notebook page.
/// warning When generating a sharable URL, if the URL exceeds 2000 characters, it will fail. This is to ensure that generated, sharable URLs will work on all systems. Larger snippets must be implemented in a separate gist. ///
Currently, each playground that is created is sandboxed such that they do not share information. They just include whatever Python functionality that Pyodide provides out the box along with access to ColorAide.
The notebook is not as complicated or feature rich as scientific notebooks, but it does allows for creating simple pages of notes with access to live Python examples that showcase what ColorAide is capable of.
The ColorAide library provides a rich API for working with colors, but for better example, Playgrounds have access to a few special in browser tools.
| Function | Description |
|---|---|
Row |
Row allows you to group a number of color swatches to a row all by them selfs. |
Ramp |
Ramp wraps a list of colors in a CSS linear-gradient. To control gradient color space, steps, etc. Ramp is not needed and coloraide.interpolate can be used. |
Steps |
Creates a color bar containing discrete steps from a list of colors. |
Row(['red', 'green'])
Row(['blue', 'orange'])
Ramp(['red', 'green'])
Color.interpolate(['red', 'green'], space='lab')
Steps(['red', 'green', 'orange', 'blue'])Notebook sources can be either an external Markdown or Python file. Markdown files are rendered as they are provided while Python files will be wrapped in a playground code block. Additionally, the notebook will accept Python code encoded in the URL which is how the "Share" button on all the "playground" code blocks format their links.
By clicking the notebook icon in the upper right corner of the page, a user can directly edit the content of the current page. All changes are temporary and are never saved. They are rendered locally with JavaScript in your browser.
More permanent pages can be created and stored in a GitHub repository, gist, or some other site as long as a link to the raw text can be passed to the notebook. To load up a page from such a source, simply click the Markdown or Python button in the top right corner of the page and paste a URL to the raw text to be parsed.
Below outlines the URL parameters that are used to load Markdown and Python content along with sharable links.
| Inputs | URL\ Parameters | Description |
|---|---|---|
| Page\ Source | ?notebook= |
Markdown input via an external, raw text link. |
| Python\ Source | ?source= |
Python source code input via an external, raw text link. |
| Code | ?code= |
Python source code passed only via search parameters in the URL. |