Writing Docs with Kate

Kate (KDE Advanced Text Editor) is a Free and Open Source text editor, available for Linux, Windows and macOS.

For documentation writers, the integrated Git features of Kate can help simplify the writing process. You do not need to remember Git commands and type them in the terminal every time you make changes to files or switch branches.

This article focuses on key features of Kate for contributors working on various Fedora documentation repositories. The capabilities can be extended to other documentation repositories.

Preparations For Using Kate With Your Repository

1. Add SSH key to settings of your account on Pagure, GitLab or GitHub.
   • On Pagure, go to My Settings – SSH Keys – Add SSH Key
   • On GitLab, Preferences – User Settings – Add an SSH Key
   • On GitHub, Settings – SSH and GPG keys – New SSH key
2. Fork a project: Go to the upstream repository and select the Fork button
3. Clone the repository
   • In your forked repository, select Clone with SSH.
   • Next, copy that link to your clipboard and paste it in GIT URL in terminal.
   • When cloning a repository, you can specify the new directory name as an additional argument. $ git clone <GIT URL> new directory
4. Install Kate. If you are Linux users, go to the packager manager of your distro to install Kate. If you use Fedora Linux, we recommend the Fedora Linux RPM version or Flatpak.

Sessions

Sessions in Kate text editor keep separate projects grouped together and help you work with multiple documentation repositories in a single view.

To save repositories in a session:

Go to the File, pull down menu – Select Open folder – Choose the cloned directory.
From the Sessions, pull down menu – Select Save session – Enter a session name – Press OK.

On the left pane, click project list saved to a new session ‘Magazine’. Next time you open Kate, the cloned repositories saved to the session will reappear.

Using the Status Bar to checkout a branch

With Kate editor, you can switch branches or create a new branch on the status bar and pop-up screen.

The current branch is shown in the lower right corner in the status bar.
To create a new branch, select Main branch.
From the popup menu select Create New Branch and enter a new branch name.

Built-in support for AsciiDoc highlighting

Files with the AsciiDoc extension will automatically be highlighted using the rules in asciidoc.xml. You don’t need to install external plugins.

On-the-fly spell checking

If you want automatic spell checking as you type, press Ctrl + Shift + O. This key combination will toggle spell check on and off.

Git toolview

The toolview on the left pane shows the git status of each open files.

Staged means the files are added (same as Git add) and will be committed if you select the Commit button at the top.

Modified shows the changes that are not staged yet.

Click the Commit button at the top of the left panel to show the diff for that commit. This will open the selected commit in the Commit toolview. If you want to see all the changes in the commit, right click and select Show Full Commit. Add a commit message.

git push button is to the right of the commit button. git pull button is to the right of the git push button.

Select the refresh icon (circular arrows) to see what has been going on with staged files and commits.

Integrated terminal

Press F4, or select the terminal button, to toggle the integrated terminal on and off.

You may take your writing to the next level, ensure documentation quality, by using build scripts and Vale linter via the integrated terminal.

Step 1. Run build scripts

To check document quality locally, you may run build and preview scripts in the integrated terminal. Build and preview scripts let you view the changes exactly how it will be published in Docs pages through Antora static site generator.

Note: check the README page of your Fedora documentation repositories to use the correct file name for build scripts and instructions. The following is an example:

To build and preview the site, run:

The result will be available at http://localhost:8080

To stop the preview:

Step 2. Run Vale on your text

Vale is a command line tool that checks your text for adherence to a defined style guide. Run Vale locally referring to the guide.

Credits and acknowledgements

Big thanks to Nicco, a KDE developer, who provided me with a great deal of inspiration from his video tutorial channel ‘Nicco loves Linux‘.

Kate Version used in this article was 23.08.3

Upstream documentation

The following are Fedora documentation Git repos used in this article;

Quick Docs
Kinoite User Docs
IoT User Docs
Documentation Contributors Guide