How to Customize ReText: Python Markdown Editor

In this post I’ll run through all the ReText customization options I know. I feel it’s a bit convoluted at times—perhaps I’m making it more confusing than it should be? Anyway, I hope this guide can help anyone who is new to ReText get started quickly.

Prerequisites

• Install ReText. I am on macOS 15.5 (Sequoia) and installed ReText v8.1.0, using Method B which I’ve gone over in my ReText installation guide.
• I believe the folder structure and naming conventions are slightly different with Linux, but the main gist should be the same (e.g. retext.ini vs retext.conf for the config file name).
• Therefore, the post will be referring to macOS naming conventions, with ReText running in a Python virtual environment.

Configuration File

ReText automatically creates a folder and config file upon first run in '/Users/username/.config/ReText project/Retext.ini'. This location may vary, so double check the config location by opening ReText > Preferences. At the top of the window there should be a path indicating the configuration file location.

Open the ReText.ini config file with your favourite text editor. This is where the settings made in the GUI are saved, but I found that some settings can only be added by changing the config file directly. Yours may look slightly different; just know the two main sections are [General] and [ColorScheme]. All the possible setting names are listed in the configuration wiki page on the project repo for reference. For example, the editorFont and font lines were added automatically after setting the fonts in the GUI Edit menu.

 1[General]
 2autoSave=true
 3defaultPreviewState=live-preview
 4editorFont="Source Code Pro,14,-1,5,400,0,0,0,0,0,0,0,0,0,0,1,Regular"
 5font="Inter,16,-1,5,400,0,0,0,0,0,0,0,0,0,0,1,Regular"
 6handleWebLinks=true
 7lineNumbersEnabled=true
 8markdownDefaultFileExtension=.md
 9openLastFilesOnStartup=true
10tabWidth=2
11paperSize=A4
12rightMargin=80
13rightMarginWrap=true
14saveWindowGeometry=true
15tabBarAutoHide=true
16useWebEngine=true
17windowTitleFullPath=true
18wideCursor=true
19
20[ColorScheme]
21codeSpans=red
22htmlTags=teal
23htmlStrings=skyblue
24htmlComments=pink
25markdownHeaders=orange
26markdownLinks=limegreen
27whitespaceOnEnd=grey
28blockquotes=yellow
29marginLine=orange
30lineNumberArea=pink
31lineNumberAreaText=black

Here’s the output of the [ColorScheme] settings. I’ve made each setting¹ a different colour for easy reference.

Most are self-explanatory like htmlTags. To clarify, marginLine color, which I’ve set as orange in this demonstration (you can see a thin orange line on the left panel, AKA Editor Pane, near the right margin), is the rightMargin line setting’s colour. I have set it to =80 under [General]. This is because 80 to 100 characters is the general recommendation for the printable width of an A4 piece of paper.

I have used plain English colours for easier understanding of what each setting does; but you can use hex codes for colours like codeSpans=#04D5FA for greater colour customization. Hex codes must be capitalized/upper case!

Note

If you try this out this config yourself, you may be wondering why strike-through, sub-bullets and the checkboxes in Markdown aren’t rendering on the right panel, AKA Preview Pane, like in my screenshot.

Go to the Menu bar > Edit > ‘Use WebEngine (Chromium) renderer’ and keep that on.

Depending on what Python packages are present in your venv or system, you may need to install additional Python Markdown extensions. Please refer to the Extensions section below for more information.

More Customization Power—Style Sheets

You may be wondering, other than the basic colours of Markdown syntax in the Editor Pane, can anything else be changed? The answer is yes!

There are two CSS files you can use to customize different parts of ReText:

1. styleSheet - Used to edit the Preview Pane (right) exclusively, just like in websites.
2. appStyleSheet - Used to edit the ReText interface itself and the Editor Pane (left).

Both settings should be added under [General] in the config ReText.ini file, with file path to their respective stylesheet. Remember to use quotes if there are spaces in the file path, for example:

1[General]
2appStyleSheet="/Users/username/.config/ReText project/retext_interface.css"
3styleSheet="/Users/username/.config/ReText project/retext-preview.css"

Example of retext-preview.css

Here’s a simple CSS of some beige text on a warm grey with yellow links for the right panel. Remember, you can change the font-family and font-size directly in the GUI menu bar > Edit > ‘Change editor font’ and ‘Change preview font’, which is saved in the retext.ini config file. If changes in the CSS is not seen after restarting, try adding !important to override default styles.

1body {
2  color: #D6C7AB;
3  background-color: #191916;
4}
5
6a {
7    color:#fdc200;
8}

Here is the Preview Pane after restarting the app.

The stylesheet can also be set in the GUI Preferences window.

If you are not sure what the CSS selector is for the part you want to change, simply go to the Menu bar > Edit > ‘View HTML code’. A window will pop up with the Markdown (Editor Pane) contents rendered as HTML. You can then target the selector in the stylesheet.

Example of retext-interface.css

Now, onto the second stylesheet that you can use to customize ReText. This is mainly for controlling the whole ReText interface window and also the left Editor Pane. It is based on the Qt framework and these are the selectors I’ve discovered so far that works in ReText. Use this Qt style sheet reference to get the selector names for editable sections.²

Note

Some of the colour options of the interface or Editor Pane are directly accessible in the [ColorScheme] of the config file mentioned above; e.g. lineNumberArea=pink and lineNumberAreaText=black

 1/*RETEXT INTERFACE—MIDDLE SPLIT BAR*/
 2QSplitter::handle {
 3  background: fuchsia;
 4}
 5
 6/*RETEXT INTERFACE—BORDER*/
 7QMainWindow {
 8  background: yellow;
 9}
10
11/*LEFT PANEL QTextEdit */
12ReTextEdit {
13  background-color: darkolivegreen;
14  color: white; /*LEFT PANEL TEXT COLOR*/
15}
16
17/*LEFT PANEL SCROLL BAR*/
18QScrollBar {
19    background: aqua;
20}

Here is what each CSS selector is doing with the colour coded example:

Markdown Features—Using Extensions

After customizing with stylesheets and the configuration file, there are other features/settings we can set in ReText using Python-Markdown extensions.

Here is a page with all the possible Python Markdown extensions; I am currently using these:

PyMdown Collection

• pymdown-extensions
  • pymdownx.tasklist
  • pymdownx.tilde
  • pymdownx.betterem
  • pymdownx.inlinehilite
  • pymdownx.superfences

Other Extensions

• mdx_truly_sane_lists
• mdx_breakless_lists
• mdx_codehilite

How To Install Extensions

You have the option to using these Markdown extensions for single files or globally. I prefer global extensions so we will add a markdown-extensions.txt file in /Users/username/.config/markdown-extensions.txt, with each extension in its own single line. Alternatively, you can add the extensions you want in the GUI Preferences window, separated with a comma. The list will reflect in the same file.

Tip

A file with a . (period) prefix means it is hidden. To toggle hidden files on macOS, press Command + Shift + Period.

1pymdownx.tasklist
2pymdownx.tilde
3pymdownx.superfences
4pymdownx.betterem
5pymdownx.inlinehilite
6mdx_truly_sane_lists
7mdx_breakless_lists
8mdx_codehilite

Each Python extension will have it’s own install command. So if you installed ReText in a venv like I did:

• Open Terminal and activate the venv with source /path/to/retext/venv/bin/activate.
• pip list to show currently installed packages.
• pip install package-name to install the extension you require.
• For example, for mdx_truly_sane_lists, you can install using PyPi pip install mdx_truly_sane_lists or directly from Git using pip install git+git://github.com/radude/mdx_truly_sane_lists.
• Do this for each of the extensions you added to ReText, deactivate the venv when you’re done with deactivate and restart ReText.app.
• The new features from the added extensions should be activated. If not, double check Menu > Edit > ‘Use WebEngine (Chromium) renderer’ is ticked. Make sure the actual syntax is correct, e.g. 2 space tab indents vs 4 space tab indents to nested bullet points makes a difference!

Note

You may sometimes see pip3 instead of pip in commands. Which do you use? From my understanding, because we are inside a Python virtual environment, the pip inside it will be linked to the Python interpreter which was used to create the venv in the first place (usually python3 like python3 -m venv /path/to/venv/retext-env). So the package installer is going to be pip3 in this case (the same as pip).

Therefore, there is no need to specify the version number unless we’re using the package installer outside venvs or on systems where multiple versions of Python are installed.

Pygments—Code Highlighting

A feature that is quite popular is code syntax highlighting. This requires the Pygments package to be installed and mdx_codehilite to be in the ReText extension list. To use Pygments, first install it with the same method described in the previous paragraph.

• pip install Pygments
• pygmentize -L styles to list all the support styles or visit the website.
• Choose the style you like and generate a css file in your current directory: pygmentize -S solarized-dark -f html > pygments.css
• Open the generated pygments.css, copy and paste its contents into retext-preview.css (our ReText styleSheet).
• These colours are only for code highlighting. If you want the rest of your Preview Pane to match the Pygments theme, you can try to customize the main font and background colours to complement the theme.

For example, I have used the solarized-dark Pygments theme.

  1/*MAIN PREVIEW PANE SETTINGS*/
  2body {
  3  color: #85a7b2;
  4  background-color: #171e20;
  5}
  6
  7a {
  8    color:#CB4B16;
  9    font-weight:800;
 10}
 11
 12h1, h2, h3, h4, h5, h6 {
 13    color: #8ecadc;
 14}
 15pre {
 16    background-color: #181e17;
 17    padding: 0.4rem;
 18    border: 1px solid #2AA198;
 19    border-radius: 0.5rem;
 20}
 21p code, li code, ul code {
 22    color: #268BD2;
 23    background-color: #181e17;
 24    padding: 0 0.2rem;
 25}
 26
 27/*GENERATED WITH pygmentize -S solarized-dark -f html > pygments.css FOR CODE SYNTAX HIGHLIGHTING*/
 28pre { line-height: 125%; }
 29td.linenos .normal { color: #586e75; background-color: #073642; padding-left: 5px; padding-right: 5px; }
 30span.linenos { color: #586e75; background-color: #073642; padding-left: 5px; padding-right: 5px; }
 31td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
 32span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
 33.hll { background-color: #073642 }
 34.c { color: #586E75; font-style: italic } /* Comment */
 35.err { color: #839496; background-color: #DC322F } /* Error */
 36.esc { color: #839496 } /* Escape */
 37.g { color: #839496 } /* Generic */
 38.k { color: #859900 } /* Keyword */
 39.l { color: #839496 } /* Literal */
 40.n { color: #839496 } /* Name */
 41.o { color: #586E75 } /* Operator */
 42.x { color: #839496 } /* Other */
 43.p { color: #839496 } /* Punctuation */
 44.ch { color: #586E75; font-style: italic } /* Comment.Hashbang */
 45.cm { color: #586E75; font-style: italic } /* Comment.Multiline */
 46.cp { color: #D33682 } /* Comment.Preproc */
 47.cpf { color: #586E75 } /* Comment.PreprocFile */
 48.c1 { color: #586E75; font-style: italic } /* Comment.Single */
 49.cs { color: #586E75; font-style: italic } /* Comment.Special */
 50.gd { color: #DC322F } /* Generic.Deleted */
 51.ge { color: #839496; font-style: italic } /* Generic.Emph */
 52.ges { color: #839496; font-weight: bold; font-style: italic } /* Generic.EmphStrong */
 53.gr { color: #DC322F } /* Generic.Error */
 54.gh { color: #839496; font-weight: bold } /* Generic.Heading */
 55.gi { color: #859900 } /* Generic.Inserted */
 56.go { color: #839496 } /* Generic.Output */
 57.gp { color: #268BD2; font-weight: bold } /* Generic.Prompt */
 58.gs { color: #839496; font-weight: bold } /* Generic.Strong */
 59.gu { color: #839496; text-decoration: underline } /* Generic.Subheading */
 60.gt { color: #268BD2 } /* Generic.Traceback */
 61.kc { color: #2AA198 } /* Keyword.Constant */
 62.kd { color: #2AA198 } /* Keyword.Declaration */
 63.kn { color: #CB4B16 } /* Keyword.Namespace */
 64.kp { color: #859900 } /* Keyword.Pseudo */
 65.kr { color: #859900 } /* Keyword.Reserved */
 66.kt { color: #B58900 } /* Keyword.Type */
 67.ld { color: #839496 } /* Literal.Date */
 68.m { color: #2AA198 } /* Literal.Number */
 69.s { color: #2AA198 } /* Literal.String */
 70.na { color: #839496 } /* Name.Attribute */
 71.nb { color: #268BD2 } /* Name.Builtin */
 72.nc { color: #268BD2 } /* Name.Class */
 73.no { color: #268BD2 } /* Name.Constant */
 74.nd { color: #268BD2 } /* Name.Decorator */
 75.ni { color: #268BD2 } /* Name.Entity */
 76.ne { color: #268BD2 } /* Name.Exception */
 77.nf { color: #268BD2 } /* Name.Function */
 78.nl { color: #268BD2 } /* Name.Label */
 79.nn { color: #268BD2 } /* Name.Namespace */
 80.nx { color: #839496 } /* Name.Other */
 81.py { color: #839496 } /* Name.Property */
 82.nt { color: #268BD2 } /* Name.Tag */
 83.nv { color: #268BD2 } /* Name.Variable */
 84.ow { color: #859900 } /* Operator.Word */
 85.pm { color: #839496 } /* Punctuation.Marker */
 86.w { color: #839496 } /* Text.Whitespace */
 87.mb { color: #2AA198 } /* Literal.Number.Bin */
 88.mf { color: #2AA198 } /* Literal.Number.Float */
 89.mh { color: #2AA198 } /* Literal.Number.Hex */
 90.mi { color: #2AA198 } /* Literal.Number.Integer */
 91.mo { color: #2AA198 } /* Literal.Number.Oct */
 92.sa { color: #2AA198 } /* Literal.String.Affix */
 93.sb { color: #2AA198 } /* Literal.String.Backtick */
 94.sc { color: #2AA198 } /* Literal.String.Char */
 95.dl { color: #2AA198 } /* Literal.String.Delimiter */
 96.sd { color: #586E75 } /* Literal.String.Doc */
 97.s2 { color: #2AA198 } /* Literal.String.Double */
 98.se { color: #2AA198 } /* Literal.String.Escape */
 99.sh { color: #2AA198 } /* Literal.String.Heredoc */
100.si { color: #2AA198 } /* Literal.String.Interpol */
101.sx { color: #2AA198 } /* Literal.String.Other */
102.sr { color: #CB4B16 } /* Literal.String.Regex */
103.s1 { color: #2AA198 } /* Literal.String.Single */
104.ss { color: #2AA198 } /* Literal.String.Symbol */
105.bp { color: #268BD2 } /* Name.Builtin.Pseudo */
106.fm { color: #268BD2 } /* Name.Function.Magic */
107.vc { color: #268BD2 } /* Name.Variable.Class */
108.vg { color: #268BD2 } /* Name.Variable.Global */
109.vi { color: #268BD2 } /* Name.Variable.Instance */
110.vm { color: #268BD2 } /* Name.Variable.Magic */
111.il { color: #2AA198 } /* Literal.Number.Integer.Long */

Conclusion

There’s lots of flexibility and functionality to ReText, and I am happy to say it has not crashed once on me (yet, touch wood). I have replaced Mac’s TextEdit with ReText, and I tend to use it on single Markdown files instead of a collection of them (like in Obsidian—my main PKM app). I really love the customizability; and using Markdown instead of plaintext is just a million times better!

Further Reading

• ReText’s official FAQ page
• Python Markdown Extensions