The documentation is live at: http://curculionidae.github.io/docs/
The pages are just markdown files (.md) in the /docs directory. You can edit them directly on GitHub.
Github Actions will deploy the website after you save changes.
To adjust the order and structure of the pages, adjust nav in the zensical.toml file.
For more information, refer to the authoring tutorial on the zensical documentation: https://zensical.org/docs/authoring/markdown/
Place image files in /docs/assets/images/. Then embed them using a markdown link without a leading ../:
Zensical automatically adjusts the path when building. Using ../assets/images/ or /assets/images/ will produce a broken link on the deployed site (even if it works locally).
To add a caption, use a figure block:
<figure markdown="span">
<figcaption>Your caption here.</figcaption>
</figure>Place .webm video files in /docs/assets/videos/. Embed them using a raw HTML video element with ../assets/videos/ (with the leading ../):
<video controls autoplay loop muted>
<source src="../assets/videos/yourvideo.webm" type="video/webm">
Your browser does not support the video tag.
</video>Note: the path prefix is different from images (../assets/videos/ vs assets/images/) because raw HTML tags are passed through unchanged by Zensical, while markdown image links get their path adjusted automatically.
[Learn to add sources](TutorialAddSources.md)Find the name of the .md file in this GitHub Repository. Generally, if the URL of the page is https://curculionidae.github.io/docs/TutorialAddSpecies/, the name of the .md file is TutorialAddSpecies.md.
Text in square brackets [] can be anything.
[Status and Relationships](TutorialAddSpecies.md#status-and-relationships)Make sure there is no / between the .md and #.
Text in square brackets [] can be anything.
On your local computer, you can edit the files and see a live preview of the website in your browser.
Git clone the repository to your computer. To run the site locally, you need to have the python package Zensical installed. It's recommended to install it in its own environment (use e.g. conda). Open a terminal in the directory that you cloned, activate your environment that has zensical installed, and type "zensical serve" in the terminal. The website will be built from source and served via localhost, you'll get an URL that you can open in your browser. Now you have a live preview of every edit you make to the raw files!
When you're done with your edits, git add them, git commit and git push.
Can be displayed as:
{keyword:Name} → tag / keyword
{topic:Name} → topic
{predicate:Name} → data-attribute predicate
They will be rendered with the color that is currently used for them in TaxonWorks. It's a shorthand notation that is automatically expanded to HTML at build time, color is live-read from Taxonworks whenever the page is visited.
Biological relationship tables use a shorthand notation that is automatically expanded to HTML at build time (via docs/hooks.py).
Format:
```bio-rel
subject name | object name
[subject props] | [object props]
Definition text here.
```
- Line 1 (required): relationship name on the left, inverted name on the right, separated by
| - Line 2 (optional): TaxonWorks properties in
[brackets], one side per|column — omit this line entirely if there are no properties on either side; use[props] |or| [props]if only one side has properties - Last line (required): definition text; may include inline HTML such as
<em>for italics
The bio-rel.js script (loaded via extra_javascript) converts the code blocks to HTML tables in the browser. No special build steps are needed — zensical serve and zensical build work as usual.
Example:
```bio-rel
reared from | yielded by rearing
[larva] [consumer in a trophic relationship] | [resource in a trophic relationship] [resource for larval feeding]
In most cases, a more specific biological relationship can be used, also defining the plant organ.
```
(This section is probably not relevant for you)
The file docs/stylesheets/extra.css contains custom CSS for the biological relationships tables. It is loaded via extra_css in zensical.toml.
The /// bio-rel shorthand generates tables with the following classes — do not add inline style="background-color:..." as the styling is dark-mode aware:
| Class | Meaning |
|---|---|
class="bio-rel" |
on <table>: marks a biological relationships table |
class="subject" |
on <th>: the subject/relationship-name side (gray) |
class="object" |
on <th>: the object/inverted-relationship-name side (green) |
class="props" |
on <td>: property cells (light background) |
class="note" |
on <td>: annotation rows such as asserted distribution or citation (use raw HTML for these) |
If files where changed but the website is still the same (changes should be visible within 1 minute), delete the "site" folder. It is re-generated by zensical from the source md files and can be deleted without hesitation.