Challenges

These are situations that I’ve encountered in Helix and I want a good way to handle them. This may not be the best way to solve them, but you’ve got to start somewhere.

Another way to start thinking about editing challenges can be found here at Helix Golf.

1. How to Copy Text to the System Clipboard

Start with something simple. I want to copy some selected text from within Helix to the system clipboard so that it can be copied into another application.

  1. Select text using the desired selection commands.
  2. Press "+y on the keyboard.

" - open the register selection pop up + - choose the system clipboard y - yank the selected text to the clipboard.

2. Interact with the Command Line

Thanks to this Luke Pighetti YouTube Short for the examples.

Run any shell command using :sh. The result of the command will appear in a pop-up that floats around with your cursor. To dismiss the pop-up, just press esc. Super useful for getting some reference information on screen. I don’t know of any way to interact with the pop-up, other than scrolling.

:sh git add .
:sh ls

The :insert-output command inserts the result of the command into your document. A shortcut for running :insert-output is to use !.

:insert-output date
:insert-output date -u +'%Y%m%d'

The :pipe command takes selected text, runs it through a shell command, and replaces it with the output of the command. Here is a JSON example that can be selected and reformatted with the jq utility. A shortcut for the :pipe command is the pipe symbol |.

{ "foo": "bar", "baz": [1, 2, 3, 4] }

:pipe jq
:pipe jq -c

3. How to Title Case a String of Text

There is no built-in command in Helix to title case a string of text. This is the work around that I came up with.

  • Step 1 - create a python title case script
  • Step 2 - call the script from within Helix
  • Step 3 - add a keybinding for it

What is title case? See Title Case Capitalization

Create a Python Script That Title Cases a String of Text

First I created a small python script that takes a string of text on the command line and prints out the title cased version of that string. The python file is named title.py and is stored at a location in the computer’s path (so it can be run from anywhere).

Next I had to give the python script “execute” permissions, like so:.

chmod +x title.py

Here is the code for the python title.py script file.

#!/usr/bin/python3
import sys

def main(title: str) -> str:
    result = f"{title}".title()
        return result


if __name__ == "__main__":
    answer = main(sys.argv[1])
        print(answer)

The script can be run from the command line like this:

title.py "title case me"

This prints out the result Title Case Me.

Run the Script Within Helix

Here is a title case example:

Select the line of text (or block of text) that needs to be title cased. Use the x key on a line in normal mode to select the entire line.

With the selection made, run the following command from normal mode in Helix.

:pipe title.py "%{selection}"

The selected text should be replaced with the title case version.

Create Key Binding for This Process

In order to create a key binding for title casing selected text, I modified the config.toml file found in the ~/.config/helix/ folder. In the [keys.normal] section, I added the line shown below to bind the command to the Ctrl + t key combination.

[keys.normal]
C-t = [':pipe title.py "%{selection}"']

To use this, I select the text to be title cased and then press Ctrl+t.

Conclusion

This trick could be used for any number of things to add functionality to Helix. The script doesn’t have to be python, it could be in bash, Lua, or any other programming language you’re familiar with. Basically, you’re just selecting some text and then passing it along to an external application for some processing that replaces the initial selected text.

Sometimes the python title function does not return a good title case rendering. Perhaps the script could be updated to create a title case closer to the standards.

4. How to Make the Editor Background Transparent

To create a transparent background in helix based on one of the existing themes is quite easy. In order for this to work, NOTE: you will need to set a transparency for your terminal first. Then we create a new theme file that simply ignores the background value for your theme.

  1. Go to the ~/.config/helix folder
  2. Make a themes folder if it doesn’t exist. mkdir themes.
  3. Move into the themes folder cd themes.
  4. Create a new theme file for your transparent theme touch gruvbox_transparent.toml.
  5. Edit the new gruvbox_transparent.toml theme file and add the following lines:
inherits = "gruvbox"
"ui.background" = {}
  1. This tells helix to use the gruvbox theme and the ignore any ui.background setting from the gruvbox theme.
  2. Save the gruvbox_transparent.toml file.
  3. Navigate to the ~/.config/helix/ folder and edit the config.toml file.
  4. Add the following line to the top of the config.toml file.
theme = "gruvbox_transparent"
  1. Save the .config.toml file
  2. in normal mode, enter :config-reload to reload the configuration file and see the changes.

5. How to Add Words to the Dictionary

I am using harper-ls as a grammar checker for Markdown files.

I thought I had this one solved. I was pressing space+a to perform the code action. This would pop up a menu where one of the choices is to add the word to the file dictionary. Right now, that isn’t working properly for me. I’ll have to dig into it a little deeper.

6. Generate a Markdown Preview

To generate a Markdown preview of the currently edited file is a huge help when writing articles like this. There is a lot of room to customize this solution. I started out with the basic information from the GitHub web site referenced below. But, this could be customized with different CSS files and additional pandoc options.

Requirements

This solution is based on the files and information from this site:

Markdown CSS for Pandoc

  • Pandoc must be installed. I installed pandoc with brew install pandoc but check out the options on Pandoc.org
  • Download gfm.css and gfm-hl.theme files from the referenced site.
  • A web browser of your choice. Qutebrowser

How It Works

This routine, runs a pandoc command on the current file. It uses ~/scripts/gfm.css for format the file, and uses ~/scripts/gfm-hl.theme to format any code blocks within the Markdown file. The resulting file is saved as ~/temp/tempfile.html. This HTML file is then piped into qutebrowser which runs and displays the HTML file.

The ~/temp/tempfile.html file is not deleted, it just stays there and gets overwritten each time a preview is run.

Setting Up

  • Create a ~/temp folder if it doesn’t exist.
  • Create a ~/scripts folder if it doesn’t exist.
  • Add the ~/scripts folder to your system’s path.
  • Copy the gfm.css and gfm-hl.theme files into the ~/scripts folder.
  • Create the preview script shown in the next step and save it in the ~/scripts folder.
  • I named the preview script file preview and gave is execute permissions: chmod +x preview.

Preview Script

Here is the code for the preview script. Note that file locations are hard coded in the pandoc line. So, the files locations can be changed to suit your preferences.

Also, note the web browser I’m using is called qutebrowser. It is a lightweight browser that uses vim style key bindings that go well with this process.

#!/usr/bin/env bash
# convert a markdown file into an html file with pandoc.
# Options
# $@  = take the file as the first argument.
# -s  = --standalone - produce output with appropriate header/footer
# -c gfm.css  = --css URL of css file
# -f gfm  = --from github flavored markdown
# --syntax-highlighting ~/scripts/gfm-hl.theme
# -o ~/temp/tempfile.html  = --output file (the html file)
# |  = pipe, send output to the next application in the command
# qutebrowser  = launch qutebrowser - change to the browser of your choice
# ~/temp/tempfile.html  = with the temp html file as input

# Here is the command the does all the heavy lifting.
pandoc $@ -s -c ~/scripts/gfm.css -f gfm --syntax-highlighting ~/scripts/gfm-hl.theme -o ~/temp/tempfile.html | qutebrowser ~/temp/tempfile.html

To test the set up, go to a folder that has a Markdown file and run preview myfile.md (where myfile.md is the name of your file). This should launch the browser and display an HTML rendering of the file.

Launching the Preview

While editing a Markdown file in Helix, use the following command to launch a preview of the file. Quotes are included around %{buffer_name} just in case there are spaces in the filename.

:! preview "%{buffer_name}"

Adding a Key Binding for the Preview

In order to create a key binding for previewing your Markdown file, Modify the config.toml file found in the ~/.config/helix/ folder. In the [keys.normal] section, I added the line shown below to bind the command to the Ctrl + p key combination.

[keys.normal]
C-p = [':! preview "%{buffer_name}"']

To use this, press Ctrl+p.

Conclusion

I really like this. It makes Helix a well rounded Markdown editor.

Things that could be improved:

  • How about some additional CSS possibilities to give different looks for other types of Markdown files?
  • My website uses Hugo to generate the static site pages. It includes front matter at the top of each Markdown file. Is there a way to get Pandoc to ignore that front matter and not include it in the preview?

Also See: