Writing Docs with Kate

Photo by Daria Glakteeva on Unsplash

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.

Sessions Menu

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.

Popup menu showing Create New branch

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.

Show diff

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:

$ ./docsbuilder.sh -p

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

To stop the preview:

$ ./docsbuilder.sh -k

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

Fedora Contributor Community Fedora Project community

12 Comments

  1. Darvond

    Now here’s a useful guide. Personally I prefer the simpler Mousepad for basic jots, but Kate is certainly there when I need it. And it’s so lightweight even with all the utility it has.

    When it comes to writing proper documents, I prefer Wordgrinder or WordTsar, maybe FocusWriter if I’m in the mood for a fancier interface. LibreOffice is great but is a distraction waiting to happen with all those fancy knobs, buttons, and ribbons.

    • Grateful for your comment. Always helpful to know reader’s point of view 🙂

      Like yourself, I use a much simpler editor (Kwrite or notepad++) as well if I write speech note or manuscript in general.

      I made an improvement for my writing workflow using Kate text editor. I can work through docs repos in Pagure, GitLab and GitHub without changing context. So I can stay on Kate 99% of the time I review and write user documentation, which is often code-rich.

      It all depends on working rule of team and who I will work with and review my document, and how they want me to submit a draft.

    • Alistair Cookie

      LibreOffice is a disaster waiting to happen. It should not be forced down on anyone. On any distro.

  2. aye

    Great info, thanks!
    I,myself, has been using kate for editing html related files. I like kate, it’s bestowed me certain possibilities and freedom in some area better than its counterparts.

  3. lunakitty

    Kate is amazing. It’s a pretty good alternative to VSCode too.

  4. Grandpa Leslie Satenstein

    Happy New Year to you “Hank”, and to all devoted Linux users. Special wishes include “good health, prosperity and everything positive.”

    I did read the above, and found it well done. I needed to read it twice, and then evaluate “kate” as my default graphics editor.

    Is it possible to redo your presentation for a YouTube presentation?
    It would be appreciated if you had produced a YouTube video to describe what you are documenting above, not because I have become lazy to read too many activities/details, especially when time is short.

    I tend to learn better by “monkey see, monkey do” approach to learning.

    • Hi Leslie, happy 2024 for you and your family!

      Thanks for your comments and suggestions. I understand this article is introductory one, based on key features. I made a content proposal for ‘Writing user documentation on multiple repos and Git forge’ to Fedora project.

      https://discussion.fedoraproject.org/t/writing-goals/101047#contributor-guide-3

      I’ll record the session with Kate and share the link in Fedora discourse forum (#docs-team tag) in Feb-Mar.

      Another untold benefit of using a text editor for writing is I can work on multiple documentation drafts (with lots of bash commands and comments) without internet connection. I keep adding changes offline in Kate and push changes later, so I can concentrate on wording and flow.

  5. johnatan

    actually this article is low effort one,
    It should have been written 10 years ago, and there are a lot of articles about Kate, which tell the same info as this one.

    Nowadays kate is all about new cool plugins like language server and debug server.
    You literary can set up language server for many languages and to set up debug server plugin to have debugging capability for your languages.

    For example I use Kate with go to write code with code completion and documentation, build plugin to run the code and debug plugin to debug it.

    Kate is the coolest default text editor on linux (compared to gedit, mousepad etc)
    It is not as powerful as vscode, but is very fast and eats small amout of memory.

    • Kate’s Git features are recently documented by KDE developer like this https://kate-editor.org/post/2023/2023-02-01-using-kate-git-support/

      Use case I tried is that when tech writers use multiple web interfaces of Git forge – Pagure, GitLab and GitHub, the friction started to mount and affected writer’s productivity.

      I have experimented workflow some time in 2023 at a point I can document for other colleagues I work with.

      I didn’t find anything that matches my use case. If you have one, let me know. I’d love to reference it for my how to guide.

  6. I remember I used Kate as full IDE even about 13 years ago, one of best editors ever. But now I migrated to Vim.

Comments are Closed

The opinions expressed on this website are those of each author, not of the author's employer or of Red Hat. Fedora Magazine aspires to publish all content under a Creative Commons license but may not be able to do so in all cases. You are responsible for ensuring that you have the necessary permission to reuse any work on this site. The Fedora logo is a trademark of Red Hat, Inc. Terms and Conditions