Skip to content

Minimal change to documentation #6229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jsatchell wants to merge 3 commits into
base: main
Choose a base branch
from
+8 −1
Open

Minimal change to documentation #6229

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ee74122
Minimal change to documentation
jsatchell Nov 14, 2025
fb9d37a
Merge branch 'Textualize:main' into main
jsatchell Dec 6, 2025
f8e4379
Simplified text after review by WM
jsatchell Dec 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/getting_started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,16 @@ All you need to get started building Textual apps.

## Requirements

Textual requires Python 3.9 or later (if you have a choice, pick the most recent Python). Textual runs on Linux, macOS, Windows and probably any OS where Python also runs.
Textual requires Python 3.9 or later (if you have a choice, pick the most recent Python). Textual runs on Linux, macOS, Windows and probably any OS where Python also runs. You also need a unicode font that includes the line drawing and block characters, which are used to render the controls.
Copy link
Member

@willmcgugan willmcgugan Dec 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is going to confuse many developers who aren't familiar with these terms. I think we can drop this sentence.


!!! info "Your platform"

### :fontawesome-brands-linux: Linux (all distros)

All Linux distros come with a terminal emulator that can run Textual apps.

The linux console is more limited and not all fonts are suitable. See [Linux console]](./linux-console.md) for details.
Copy link
Member

@willmcgugan willmcgugan Dec 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May devs will not know the difference between the linux console and the terminal on their desktop.

Suggest clarification:

"If you are using the Linux console (rather than a desktop environment), see Linux Console ...]"


### :material-apple: macOS

The default terminal app is limited to 256 colors. We recommend installing a newer terminal such as [iterm2](https://iterm2.com/), [Ghostty](https://ghostty.org/), [Kitty](https://sw.kovidgoyal.net/kitty/), or [WezTerm](https://wezfurlong.org/wezterm/).
Expand Down
5 changes: 5 additions & 0 deletions docs/linux-console.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
## Linux Console

The Linux console has limited capabilities, to maintain back compatibility with legacy VGA hardware. It supports unicode but colours are restricted and the fonts have very limited numbers of glyphs. There is a choice of 256 glyphs with 16 colors or 512 glyphs with 8 colors. Textual really needs more than 8 colors, so a font with 256 glyphs is needed. The console uses fonts in a special PSF file type; these are often in the directory /usr/share/consolefonts/.
Copy link
Member

@willmcgugan willmcgugan Dec 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, but this copy is difficult to parse. Many people reading this will be far less technical that you.

Let's keep it simple. Something along these lines:

The Linux console is less graphically capable than the terminal emulator on your desktop.
If you find your app does not look great with the default configuration, see font-for-textual for a possible solution.

You can be as technical as you like in your repo!


Textual uses line drawing and block characters to render the widgets. Many of the widely available font files lack a full set of block drawing characters, and this gives a poor appearance. The Unifoundry project have a 512 glyph font that includes all the characters needed, but this only gives you eight colors. A subset of the Unifoundry font has been developed for use with textual and you can find it at [font-for-textual](https://github.com/jsatchell/font-for-textual).