PyRST Toolbar Guide¶

Complete guide to all toolbar buttons and the RST syntax they generate.

Overview ¶

The PyRST toolbar provides quick access to common reStructuredText formatting. All buttons insert valid RST syntax at the cursor position or wrap selected text.

Button Behavior ¶

With selection: Transforms selected text

Without selection: Inserts template with placeholder text

Header Buttons ¶

H1 - Top-Level Heading ¶

Button: H1

Icon: Text “H1”

RST Syntax:

Heading Text
============

Underline Character: = (equals signs)

How to use:

Select text or place cursor
Click H1 button
Heading and underline inserted

Examples:

With selection “Introduction”:

Introduction
============

Without selection:

Heading 1
=========

Tips:

H1 is typically used for document title
Should only appear once per document
Underline must be same length as heading text

H2 - Section Heading ¶

Button: H2

Icon: Text “H2”

RST Syntax:

Section Name
------------

Underline Character: - (hyphens)

Use Cases:

Main sections of document
Subsections under H1
Most common heading level

Examples:

With selection “Features”:

Features
--------

Without selection:

Heading 2
---------

H3 - Subsection Heading ¶

Button: H3

Icon: Text “H3”

RST Syntax:

Subsection Title
~~~~~~~~~~~~~~~~

Underline Character: ~ (tildes)

Use Cases:

Subsections under H2
Third-level hierarchy
Detailed topic headings

Examples:

With selection “Installation”:

Installation
~~~~~~~~~~~~

Without selection:

Heading 3
~~~~~~~~~

Text Formatting ¶

Bold - Strong Emphasis ¶

Button: Bold icon (B)

Icon: Feather “bold” icon

RST Syntax:

**bold text**

Renders as: bold text

How to use:

Select text to make bold
Click bold button
Text wrapped with **

Examples:

With selection “important”:

**important**

Without selection:

**text**

(with “text” selected for easy replacement)

Tips:

No spaces between ** and text
Can be used inline within sentences
Nested formatting not recommended

Italic - Emphasis ¶

Button: Italic icon (I)

Icon: Feather “italic” icon

RST Syntax:

*italic text*

Renders as: italic text

How to use:

Select text to italicize
Click italic button
Text wrapped with *

Examples:

With selection “note”:

*note*

Without selection:

*text*

Tips:

Single * for italic (vs double for bold)
No spaces between * and text
Cannot start with * if at beginning of line (would be bullet list)

Code - Inline Code ¶

Button: Code icon (</>)

Icon: Feather “code” icon

RST Syntax:

``inline code``

Renders as: inline code

How to use:

Select code snippet
Click code button
Text wrapped with ` `` `

Examples:

With selection “print(‘hello’)”:

``print('hello')``

Without selection:

``text``

Use Cases:

Function names: calculate()
Variable names: user_name
File paths: /path/to/file
Commands: ls -la
Code snippets: x = 42

Tips:

Use double backticks (not single like Markdown)
No spaces between ` `` ` and text
For multi-line code, use code block instead

Lists ¶

UL - Bullet List ¶

Button: List icon

Icon: Feather “list” icon

RST Syntax:

- Item 1
- Item 2
- Item 3

Smart Behavior:

On empty line: Inserts 3 placeholder items
```
- Item 1
- Item 2
- Item 3
```

With selected text: Converts each line to list item

First item
Second item
Third item

Becomes:

- First item
- Second item
- Third item

In existing list: Adds next item

- Existing item
- New item  ← cursor here after click

On non-empty line: Converts line to list item
```
This is text
```
Becomes:
```
- This is text
```

Nested Lists:

- Top level

  - Nested item (2 spaces indent)
  - Another nested item

- Back to top level

Tips:

Must have space after -
Blank line between list and other content
Indent by 2 spaces for nesting
Can mix with other list types

OL - Numbered List ¶

Button: Hash icon (#)

Icon: Feather “hash” icon

RST Syntax:

Item 1
Item 2
Item 3

Smart Behavior:

On empty line: Inserts 3 numbered items
```
1. Item 1
2. Item 2
3. Item 3
```
With selected text: Converts lines to numbered list
```
First step
Second step
```
Becomes:
```
1. First step
2. Second step
```

In existing list: Adds next numbered item

First
Second
Third  ← auto-incremented

On non-empty line: Converts to item #1

Alternative Syntax:

#. Auto-numbered item
#. Auto-numbered item
#. Auto-numbered item

(docutils auto-numbers with #.)

Nested Lists:

1. Top level

   a. Nested with letters
   b. Another nested

2. Back to top level

Tips:

Numbers auto-increment in rendering
Can use any number sequence (e.g., all 1’s)
Indent by 3 spaces for nesting
Can mix with bullet lists

Links & Media ¶

Link - Hyperlink ¶

Button: Link icon

Icon: Feather “link” icon

RST Syntax:

`Link text <https://example.com>`_

Renders as: Link text

How to use:

Select link text (or leave cursor)
Click link button
Replace placeholder URL

Examples:

With selection “Click here”:

`Click here <https://example.com>`_

Without selection:

`Link text <https://example.com>`_

(entire construct is selected for editing)

Link Types:

External links:

`Python Website <https://www.python.org>`_

Direct URLs:
```
https://www.example.com
```
(auto-linked by docutils)

Named references:

See the `Introduction`_ section.

.. _Introduction: #intro

Email links:
```
`Email me <mailto:user@example.com>`_
```

Tips:

Note the trailing underscore _
Backticks around entire link construct
Spaces allowed in link text
URL can be relative or absolute

Image - Insert Image ¶

Button: Image icon

Icon: Feather “image” icon

RST Syntax:

.. image:: /path/to/image.png
   :alt: Image description
   :width: 400

Renders: Displays image in preview

How to use:

Click image button
Replace path with actual image URL/path
Update alt text
Adjust width if needed

Image Options:

.. image:: /path/to/image.png
   :alt: Alternative text
   :width: 400px
   :height: 300px
   :align: center
   :target: https://example.com

Alignment Options:

:align: left
:align: center
:align: right

Figure with Caption:

.. figure:: /path/to/image.png
   :alt: Alt text
   :width: 500px

   **Figure 1:** Caption text here.

   Optional legend text.

Tips:

Indent option lines by 3 spaces
Use absolute URLs for online images
Relative paths work for local files
Alt text important for accessibility

Block Elements ¶

Code Block - Multi-line Code ¶

Button: Terminal icon

Icon: Feather “terminal” icon

RST Syntax:

.. code-block:: python

   # Your code here
   print("Hello, World!")

Renders: Syntax-highlighted code block

How to use:

Select code (optional)
Click code block button
Code is indented and wrapped

Examples:

With selection:

.. code-block:: python

   def hello():
       print("Hello!")

Without selection:

.. code-block:: python

   # Your code here
   print("Hello, World!")

Language Options:

python
javascript
bash
sql
yaml
json
rst
text (no highlighting)
Many more supported

Advanced Options:

.. code-block:: python
   :linenos:
   :emphasize-lines: 2,4-6
   :caption: Example Code

   def example():
       return True

Options:

:linenos: - Show line numbers
:emphasize-lines: - Highlight specific lines
:caption: - Add caption above code

Tips:

Indent code by 3 spaces
Blank line after .. code-block::
Blank line after code block
Change language name as needed

Blockquote - Quote Text ¶

Button: Message square icon

Icon: Feather “message-square” icon

RST Syntax:

This is a blockquote.
It can span multiple lines.

Renders: Indented, styled quotation

How to use:

Select text to quote (optional)
Click blockquote button
Text is indented by 3 spaces

Examples:

With selection:

To be or not to be,
that is the question.

Without selection:

This is a blockquote.
It can span multiple lines.

Nested Quotes:

Outer quote

   Nested quote (6 spaces)

Back to outer quote

Attribution:

"The only way to do great work is to love what you do."

-- Steve Jobs

Tips:

Indent by 3 spaces minimum
Blank line before and after
Can contain other RST elements
Use for citations, quotes, examples

Table - Grid Table ¶

Button: Grid icon

Icon: Feather “grid” icon

RST Syntax:

+------------+------------+------------+
| Header 1   | Header 2   | Header 3   |
+============+============+============+
| Row 1, C1  | Row 1, C2  | Row 1, C3  |
+------------+------------+------------+
| Row 2, C1  | Row 2, C2  | Row 2, C3  |
+------------+------------+------------+

Renders: HTML table with borders

How to use:

Place cursor on empty line
Click table button
Table template inserted
Edit content, add rows as needed

Table Template:

3 columns
2 data rows
Header row with = separator

Customizing Tables:

Add Row:

+------------+------------+------------+
| New Row    | New Data   | More Data  |
+------------+------------+------------+

Add Column:

Increase width and add column:

+-------+-------+-------+-------+
| Col 1 | Col 2 | Col 3 | Col 4 |
+=======+=======+=======+=======+
| Data  | Data  | Data  | Data  |
+-------+-------+-------+-------+

Cell Spanning:

+------------+------------+
| Spans      | Normal     |
| two rows   +------------+
|            | Data       |
+------------+------------+

Alternative: Simple Tables:

=====  =====  ======
  A      B    Result
=====  =====  ======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  ======

Tips:

Grid tables are verbose but flexible
Use monospace font for alignment
Copy and modify existing rows
Check alignment carefully
Simple tables easier for basic data

Tips & Tricks ¶

General Tips ¶

Preview First: Check preview before exporting
Use Templates: Toolbar inserts proper syntax
Read Errors: Error panel shows syntax issues
Check Alignment: RST is whitespace-sensitive
Blank Lines: Separate blocks with blank lines

Common Patterns ¶

Document Structure:

================
Document Title
================

Introduction
============

First paragraph text.

Section 1
---------

Subsection
~~~~~~~~~~

Content here.

Code Documentation:

Function Name
-------------

.. code-block:: python

   def example(arg):
       """Docstring."""
       return arg * 2

**Parameters**:

- ``arg`` - Input value

**Returns**: Doubled value

Lists with Code:

Installation steps:

1. Install dependencies::

       pip install -r requirements.txt

2. Run setup::

       python setup.py install

3. Test installation::

       pytest tests/

Keyboard Workflow ¶

Tab: Navigate toolbar buttons
Enter: Activate focused button
Type: Continue editing
Ctrl+A: Select all
Click toolbar: Transform selection

Quick Reference ¶

Element	Syntax	Button
H1	`====`	H1
H2	`----`	H2
H3	`~~~~`	H3
Bold	`text`	B
Italic	`text`	I
Code	``text``	`</>`
Bullet	`- item`
Number	`1. item`	#
Link	` `text <url>`_ `	Link
Image	`.. image::`	Image
Code Block	`.. code-block::`	Terminal
Quote	`` text``	Quote
Table	`+--+--+`	Grid

Keyboard Shortcuts ¶

Current Status: No built-in keyboard shortcuts yet.

Future Plans (see TODO.md):

Ctrl+B: Bold
Ctrl+I: Italic
Ctrl+K: Link
Ctrl+Shift+C: Code block
Ctrl+1/2/3: Headers
Ctrl+L: Bullet list
Ctrl+Shift+L: Numbered list

Workaround:

Use browser accessibility features to tab to buttons and press Enter.

Advanced Usage ¶

Combining Elements ¶

List with code:

- Install package::

      pip install pyrst

- Run application::

      python -m pyrst

Table with links:

+---------+------------------------------------------+
| Package | Documentation                             |
+=========+==========================================+
| NumPy   | `Link <https://numpy.org>`_              |
+---------+------------------------------------------+
| Pandas  | `Link <https://pandas.pydata.org>`_      |
+---------+------------------------------------------+

Code with emphasis:

Use the ``**kwargs`` pattern for **variable** arguments.

Custom Directives ¶

Note admonition:

.. note::

   This is important information for the reader.

Warning admonition:

.. warning::

   This operation cannot be undone!

See Also:

.. seealso::

   - :ref:`related-section`
   - `External link <https://example.com>`_

Complex Example ¶

Advanced Features
=================

Code Execution
--------------

PyRST supports **syntax highlighting** for code blocks:

.. code-block:: python
   :linenos:
   :emphasize-lines: 3,5

   def fibonacci(n):
       """Calculate Fibonacci number."""
       if n <= 1:
           return n
       return fibonacci(n-1) + fibonacci(n-2)

**Key points**:

- Recursive implementation
- Uses ``**kwargs`` pattern
- See `Python docs <https://docs.python.org>`_ for more

.. note::

   This is O(2^n) complexity. Use memoization for better performance.

Last Updated: 2025-11-15

See Also: