使用 Kate 编写文档
Kate 编辑器
![](/data/attachment/album/202401/22/100139stdtdd13ds13353c.jpg)


Kate（**K**DE **A**dvanced **T**ext **E**ditor）是一款自由开源的文本编辑器，适用于 Linux、Windows 和 macOS。


对于文档编写者来说，Kate 集成的 Git 功能可以帮助简化编写过程。你无需记住 Git 命令，也无需在每次更改文件或切换分支时在终端中输入它们。


本文重点为从事各种 Fedora 文档仓库的贡献者介绍 Kate 的主要功能。这些功能可以扩展到其他文档仓库。


### 将 Kate 与你的仓库一起使用的准备工作


1. 将 SSH 密钥添加到 Pagure、GitLab 或 GitHub 上的帐户设置中。
	* 在 Pagure 上，转到 <ruby> 我的设置 <rt>  My Settings </rt></ruby> – <ruby> SSH 密钥 <rt>  SSH Keys </rt></ruby> – <ruby> 添加 SSH 密钥 <rt>  Add SSH Key </rt></ruby>
	* 在 GitLab 上，<ruby> 首选项 <rt>  Preferences </rt></ruby> – <ruby> 用户设置 <rt>  User Settings </rt></ruby> – <ruby> 添加 SSH 密钥 <rt>  Add an SSH Key </rt></ruby>
	* 在 GitHub 上，<ruby> 设置 <rt>  Settings </rt></ruby> – <ruby> SSH 和 GPG 密钥 <rt>  SSH and GPG keys </rt></ruby> – <ruby> 新的 SSH 密钥 <rt>  New SSH key </rt></ruby>
2. 复刻项目：转到上游仓库并选择 “<ruby> 复刻 <rt>  Fork </rt></ruby>” 按钮
3. 克隆仓库
	* 在你的分叉仓库中，选择 “<ruby> 使用 SSH 克隆 <rt>  Clone with SSH </rt></ruby>”。
	* 接下来，将该链接复制到剪贴板并将其粘贴到终端中的 GIT URL 中。
	* 克隆仓库时，你可以指定新目录名称作为附加参数。`$ git clone <GIT URL> 新目录`
4. 安装 Kate。如果你是 Linux 用户，请转到发行版的包管理器来安装 Kate。如果你使用 Fedora Linux，我们推荐 Fedora Linux RPM 版本或 Flatpak。


### 会话


Kate 文本编辑器中的会话功能可以将单独的项目分组在一起，并帮助你在单个视图中处理多个文档仓库。


要将仓库保存在会话中：


转到 “<ruby> 文件 <rt>  File </rt></ruby>” 下拉菜单 – 选择 “<ruby> 打开文件夹 <rt>  Open folder </rt></ruby>” – 选择克隆的目录。


从 “<ruby> 会话 <rt>  Sessions </rt></ruby>” 下拉菜单中 – 选择 “<ruby> 保存会话 <rt>  Save session </rt></ruby>” – 输入会话名称 – 按 “<ruby> 确定 <rt>  OK </rt></ruby>”。


在左侧窗格中，单击 “<ruby> 项目列表 <rt>  project list </rt></ruby>” 保存到新会话“Magazine”。下次打开 Kate 时，保存到会话中的克隆仓库将重新出现。


![Sessions Menu](/data/attachment/album/202401/22/100303o37vnav49ep963z0.png)


### 使用状态栏签出分支


使用 Kate 编辑器，你可以在状态栏和弹出屏幕上切换分支或创建新分支。


当前分支显示在状态栏的右下角。


要创建新分支，请选择 “Main” 分支。从弹出菜单中选择 “<ruby> 创建新分支 <rt>  Create New Branch </rt></ruby>” 并输入新分支名称。


![Popup menu showing Create New branch](/data/attachment/album/202401/22/100303c198h26j58nco2i6.png)


### 对 AsciiDoc 高亮显示的内置支持


具有 AsciiDoc 扩展名的文件将使用 `asciidoc.xml` 中的规则自动高亮显示。你不需要安装外部插件。


### 即时拼写检查


如果你希望在输入时自动进行拼写检查，请按 `Ctrl + Shift + O`。此组合键将打开和关闭拼写检查。


### Git 工具视图


左侧窗格中的工具视图显示每个打开文件的 Git 状态。


![Show diff](/data/attachment/album/202401/22/100304sghr33c0gopmhmbz.png)


“<ruby> 已暂存 <rt>  Staged </rt></ruby>” 表示文件已添加（与 Git 添加相同），并且如果你选择顶部的 “<ruby> 提交 <rt>  Commit </rt></ruby>” 按钮，文件将被提交。


“<ruby> 已修改 <rt>  Modified </rt></ruby>” 显示尚未暂存的更改。


单击左侧面板顶部的 “<ruby> 提交 <rt>  Commit </rt></ruby>” 按钮以显示该提交的差异。这将在提交工具视图中打开选定的提交。如果你想查看提交中的所有更改，请右键单击并选择 “<ruby> 显示完整提交 <rt>  Show Full Commit </rt></ruby>”，添加一个提交消息。


Git “<ruby> 推送 <rt>  Push </rt></ruby>” 按钮在 “<ruby> 提交 <rt>  Commit </rt></ruby>” 按钮的右边。Git “<ruby> 拉取 <rt>  Pull </rt></ruby>” 按钮在 “<ruby> 推送 <rt>  Push </rt></ruby>” 按钮的右边。


选择 “<ruby> 刷新 <rt>  Refresh </rt></ruby>” 图标（圆圈箭头）以查看暂存文件和提交的情况。


### 集成终端


按 `F4` 或选择 “<ruby> 终端 <rt>  Terminal </rt></ruby>” 按钮可打开和关闭集成终端。


你可以通过集成终端使用构建脚本和 Vale linter，将你的写作提升到一个新的水平，确保文档质量。


#### 步骤 1. 运行构建脚本


要在本地检查文档质量，你可以在集成终端中运行构建和预览脚本。构建和预览脚本可让你准确查看更改如何通过 Antora 静态站点生成器在文档页面中发布。


注意：检查 Fedora 文档仓库的 README 页面，为构建脚本和说明使用正确的文件名。下面是一个例子：


要构建和预览站点，请运行：



```
$ ./docsbuilder.sh -p

```

结果可访问 <http://localhost:8080>


要停止预览：



```
$ ./docsbuilder.sh -k

```

#### 步骤 2. 对你的文本运行 Vale


Vale 是一个命令行工具，用于检查文本是否符合定义的样式指南。参考该 [指南](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-vale-linter/) 在本地运行 Vale。


### 鸣谢


非常感谢 KDE 开发人员 Nicco，他的视频教程频道 “[Nicco loves Linux](https://www.youtube.com/c/Niccol%C3%B2Ve)” 给了我很多灵感。


本文使用的 Kate 版本为 23.08.3



> 
> **[上游文档](https://docs.kde.org/stable5/en/kate/kate/index.html)**
> 
> 
> 


以下是本文使用的 Fedora 文档 Git 仓库：


* [快速文档](https://pagure.io/fedora-docs/quick-docs.git)
* [Kinoite 用户文档](https://pagure.io/fedora-kde/kinoite-docs.git)
* [IoT 用户文档](https://github.com/fedora-iot/iot-docs.git)
* [文档贡献者指南](https://gitlab.com/fedora/docs/community-tools/documentation-contributors-guide.git)


*（题图：DA/519568d2-a224-4075-a751-a1a8bc702079）*




---


via: <https://fedoramagazine.org/writing-docs-with-kate-and-git/>


作者：[Hank Lee](https://fedoramagazine.org/author/hankuoffroad/) 选题：[lujun9972](https://github.com/lujun9972) 译者：[geekpi](https://github.com/geekpi) 校对：[wxy](https://github.com/wxy)


本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出


OK
Kate (**K**DE **A**dvanced **T**ext **E**ditor) 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

- 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

- Fork a project: Go to the upstream repository and select the Fork button
- 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

- 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](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-vale-linter/).

## 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](https://www.youtube.com/c/Niccol%C3%B2Ve)‘.

Kate Version used in this article was 23.08.3

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

[Quick Docs](https://pagure.io/fedora-docs/quick-docs.git)[Kinoite User Docs](https://pagure.io/fedora-kde/kinoite-docs.git)[IoT User Docs](https://github.com/fedora-iot/iot-docs.git)[Documentation Contributors Guide](https://gitlab.com/fedora/docs/community-tools/documentation-contributors-guide.git)

## 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.

## Hank Lee

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.

## 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.

## lunakitty

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

## Ernesto di Terribile

I take VSCodium over VSCode every day

## Alistair Cookie

what a helpful comment.

## 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.

## Hank Lee

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.

## 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.

## Hank Lee

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.

## Dmitri

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