Introduction

The way that Rogallo works can be configured using a configuration file. This section will describe what can be configured and how.

The location of the configuration file will depend on your operating system and its settings; but by default it is looked for in $XDG_CONFIG_HOME, in a rogallo subdirectory. Mostly this will translate to the file being called ~/.config/rogallo/configuration.json.

Tip

You can discover the exact directory with the directories command line command

ANSI escape sequence support

Rogallo supports ANSI escape sequences in the content of pages. This means that sites can do all sorts of wonderfully colourful things:

If you would prefer that ANSI escape sequences aren't processed, and instead are stripped from the content, you can use the Toggle ANSI Escape Sequence Handling command (ToggleANSIEscapeSequenceHandling, bound to Shift+F6 by default).

Admittedly, in this case the stripped version isn't anywhere near as interesting, but in most cases you'll get the content you were seeing, just without colour.

The setting itself is saved in the configuration file as handle_ansi_escape_sequences, which takes true or false as valid values. It will be true (handle ANSI sequences) by default:

"handle_ansi_escape_sequences": true

Bookmarks manager visible

Rogallo has a sidebar that displays the bookmarks manager. By default it isn't visible. It can be made visible with the Toggle Bookmarks Manager command (ToggleBookmarks, bound to F3 by default).

The setting itself is saved in the configuration file as bookmarks_visible, which takes true or false as valid values. It will be false (not visible) by default:

"bookmarks_visible": false

Connection settings

Rogallo imposes some limits on connections to capsules. These include the connection timeout, the read timeout and the maximum number of redirects that will be handled. If you wish to modify these you can change the following values:

"connection_timeout": 10,
"read_timeout": 30,
"maximum_redirects": 5,

connection_timeout and read_timeout are an integer number of seconds. maximum_redirects is an integer number of redirections that will be followed.

Content cache

Rogallo uses a content cache to make some forms of navigation between pages faster, reducing the need to connect to a capsule and download data. The cache_ttl configuration setting controls how long a cache entry is used before it is considered stale. This is an integer number of seconds, set to 3600 (1 hour) by default.

"cache_ttl": 3600

If you would prefer to not use a cache at all, this can be turned off via the with_cache setting. Valid values are true and false, set to true by default.

"with_cache": true

Command line position

By default, Rogallo's command line appears at the bottom of the screen, above the footer of the application. It can be moved to the top of the screen, below the application header, with the Change Command Line Location command (ChangeCommandLineLocation, bound to Ctrl+Up by default).

The setting itself is saved in the configuration file as command_line_on_top, which takes true or false as valid values. It will be false (at the bottom) by default:

"command_line_on_top": false

Disable animations

Rogallo is built using the Textual framework. Textual has a tendency to go overboard with animations when scrolling content. Some people like this, some don't. For some it's an accessibility issue. If you would prefer that such animations are disabled, set the disable_animations configuration setting. It accepts true or false as valid values. It will be false (use animations) by default:

"disable_animations": false

Displayable content types

By default Rogallo only considers a narrow set of MIME types as displayable in the application. In the event that you need to expand this list, you can change the value of displayable_content_types:

"displayable_content_types": []

Note that there is a hard-coded set of types that will always be handled; changing this value adds to that list.

Important

Rogallo is currently only capable of displaying text-based content, showing either rendered Gemtext or plain text. Adding other MIME types might cause unwanted or unpredictable results.

Emoji removal

Some people find the use of emoji in Gemtext off-putting. Rogallo has a configuration option for those people. The Toggle Emoji Removal command (ToggleEmojiRemoval, bound to F6 by default) can be used to clean things up.

So, if presented with this:

you can run the command and the content will look more like this:

The setting itself is saved in the configuration file as the strip_emoji configuration setting. It accepts true or false as valid values. It will be false (don't remove) by default.

"strip_emoji": false

Gopher item badges

When showing Gopher maps Rogallo will optionally prefix lines with a "badge" related to the type of line. This can be turned off in the configuration file using the gopher_show_type_badges setting. Valid values are true (show badges) and false (don't show badges). It is true by default.

"gopher_show_type_badges": true

You can also control what text is shown for which Gopher type. This is done with a type code to string mapping called gopher_type_badges. By default the values are various characters themed after the types:

"gopher_type_badges": {
    "0": "\ud83d\udcc4",
    "1": "\ud83d\udcc1",
    "2": "\ud83d\udcc7",
    "3": "\u274c",
    "4": "\ud83d\udce6",
    "5": "\ud83d\udcbe",
    "6": "\ud83d\udcdc",
    "7": "\ud83d\udd0d",
    "8": "\ud83d\udda5\ufe0f",
    "9": "\ud83d\udce6",
    "i": "\u2139\ufe0f",
    "g": "\ud83d\uddbc\ufe0f",
    "I": "\ud83d\uddbc\ufe0f",
    "h": "\ud83c\udf10",
    "d": "\ud83d\udcc4",
    "s": "\ud83c\udfb5",
    "P": "\ud83d\udcc4",
    "X": "\ud83d\udcc4",
    "unknown": "\u2753"
}

If you wish to show different text, change the values for each of the item types. For example, if you wanted to use simple three-latter codes:

"gopher_type_badges": {
    "0": "(TXT)",
    "1": "(DIR)",
    "2": "(CSO)",
    "3": "(ERR)",
    "4": "(HQX)",
    "5": "(DOS)",
    "6": "(UUE)",
    "7": "(FND)",
    "8": "(TEL)",
    "9": "(BIN)",
    "i": "(INF)",
    "g": "(GIF)",
    "I": "(IMG)",
    "h": "(WEB)",
    "d": "(DOC)",
    "s": "(SND)",
    "P": "(PDF)",
    "X": "(XML)",
    "unknown": "(???)"
}

History manager visible

Rogallo has a sidebar that displays the history manager. By default it isn't visible. It can be made visible with the Toggle History command (ToggleHistoryManager, bound to F2 by default).

The setting itself is saved in the configuration file as history_visible, which takes true or false as valid values. It will be false (not visible) by default:

"history_visible": false

Home page

Rogallo has a home page setting. This can be set using the Set Home command (SetHome, bound to Alt+h by default). This sets the currently-visited page as the home page. If you wish you can also modify it in the configuration file:

"home_page": "gemini://geminiprotocol.net/"

Icons

Three main "icons" are used within a rendered document:

• Links within a Gemini capsule
• Finger links
• Links outwith a Gemini capsule
• List item bullet

If, for any reason, you don't like the character choices made by Rogallo for these icons, you can modify these values in the configuration file:

"geminispace_link_icon": "\u2aa2",
"fingerspace_link_icon": "\u261b",
"otherspace_link_icon": "\u2197",
"list_item_bullet_icon": "\u2022"

Keyboard bindings

Rogallo allows for a degree of configuration of its keyboard bindings; providing a method for setting up replacement bindings for the commands that appear in the command palette.

Bindable commands

The following commands can have their keyboard bindings set:

• AboutThisPage - Show information about the current page
  • Default: f7
• AddLocationToBookmarks - Add the current location to the bookmarks
  • Default: ctrl+b
• Backward - Move backward through history
  • Default: ctrl+left_square_bracket
• ChangeCommandLineLocation - Swap the position of the command line between top and bottom
  • Default: ctrl+up, ctrl+down
• ChangeTheme - Change the application's theme
  • Default: f9
• ClearCache - Clear the cache for all content
  • Default: shift+f5
• CopyDocumentToClipboard - Copy the current document to the clipboard.
  • Default: alt+shift+c
• CopyLocationToClipboard - Copy the current location to the clipboard.
  • Default: ctrl+shift+c
• Forward - Move forward through history
  • Default: ctrl+right_square_bracket
• GoHome - Go to the home page
  • Default: ctrl+h
• GoToParent - Go to the parent directory
  • Default: alt+up
• GoToRoot - Go to the root directory
  • Default: alt+shift+up
• HandOffToOperatingSystem - Hand off the current location to the operating system
  • Default: ctrl+shift+o
• Help - Show help for and information about the application
  • Default: f1, ?
• JumpToCommandLine - Jump to the command line
  • Default: /, ctrl+1
• JumpToDocument - Jump to the document viewer
  • Default: ctrl+slash, ctrl+g, ctrl+2
• JumpToSidebar - Jump to the sidebar
  • Default: ctrl+3
• OpenFile - Open a file in the local filesystem
  • Default: ctrl+o
• PipeDocument - Pipe the current document to an external command
  • Default: ctrl+shift+p
• Quit - Quit the application
  • Default: f10, ctrl+q
• Reload - Reload the current document
  • Default: ctrl+r, f5
• SaveSource - Save the source of the current document to a file
  • Default: ctrl+s
• SearchBookmarks - Search the bookmarks for a location
  • Default: f3
• SearchHistory - Search the history for a location
  • Default: f2
• SetHome - Set the home page to a specific location
  • Default: alt+h
• SetHomeToCurrentLocation - Set the home page to the current location
  • Default: ctrl+shift+h
• StripeLinks - Toggle the striping of links in the document viewer
  • Default: f8
• ToggleANSIEscapeSequenceHandling - Toggle the handling of ANSI escape sequences in text content
  • Default: shift+f6
• ToggleBookmarksManager - Toggle the display of the bookmarks viewer
  • Default: shift+f3
• ToggleCosyLinkNumbers - Toggle the position of link numbers when they're being displayed
  • Default: super+f8
• ToggleEmojiRemoval - Toggle the removal of emoji from text content
  • Default: f6
• ToggleHistoryManager - Toggle the display of the history viewer
  • Default: shift+f2
• ToggleLinkNumbers - Toggle the display of link numbers in the document viewer
  • Default: shift+f8
• ToggleView - Toggle between rendered and source view of the document
  • Default: f4
• ViewChangeLog - View the Rogallo ChangeLog
  • Default: ctrl+shift+l

Changing a binding

If you wish to change the binding for a command, edit the configuration file and add the binding to the bindings value. For example, if you wanted to change the binding used to toggle the display of a page between a rendered view or a source view, changing it from f4 to ctrl+t, you would set bindings to this:

"bindings": {
    "ToggleView": "ctrl+t"
}

The designations used for keys is based on the internal system used by Textual; as such its caveats about what works where apply. The main modifier keys to know are shift, ctrl, alt, meta, super and hyper; letter keys are their own letters; shifted letter keys are their upper-case versions; function keys are simply f1, f2, etc; symbol keys (the likes of #, @, *, etc...) generally use a name (number_sign, at, asterisk, etc...).

Tip

If you want to test and discover all of the key names and combinations that will work, you may want to install textual-dev and use the textual keys command.

If you need help with keyboard bindings please feel free to ask.

Link jumps

In Rogallo, you can navigate to links using Tab and Shift+Tab (the method of navigating between most UI elements in the application), and you can also use the mouse. Sometimes, though, if there's lots of links, it's handy to be able to jump straight to a link. To this end Rogallo provides numeric labels:

When the viewer is focused, if you type the number of a link, that link will be highlighted:

If anyone finds this distracting, you can turn the labels off with the Toggle Link Numbers (ToggleLinkNumbers, bound to Shift+F8 by default) command.

The setting itself is saved in the configuration file as the with_link_jumps configuration setting. It accepts true or false as valid values. It will be true (with labels) by default.

"with_link_jumps": true

Cosy link jumps

By default the numeric labels for the jumps are positioned to the right of the display. This is done to keep a readable flow of text. While link stripes are provided to make it easier to know which label goes with which link, some people might prefer the labels to really cosy up with the links. For those folk the Toggle Cosy Link Numbers (ToggleCosyLinkNumbers command, bound to Super+F8 by default) command is available. The result of using it will be:

The setting itself is saved in the configuration file as the cosy_link_jumps configuration setting. It accepts true or false as valid values. It will be false (labels on the right) by default:

"cosy_link_jumps": false

Link tooltips

By default, when using a mouse, Rogallo will show a tooltip containing the target URI when you hover the mouse cursor over a link.

If this feels too cluttered it can be turned off with the show_link_tooltips setting. Valid values are true and false, with true (show the tooltips) being the default.

"show_link_tooltips": true

Maximum document width

By default a document being displayed in Rogallo will take up as much horizontal width as possible. So, if the terminal is 80 characters wide, it'll look like this:

At 120:

And even wider:

If you prefer that Rogallo always caps the width of text at a specific value, set maximum_document_width in the configuration file. A value of 0 means "no limit" (the default value). If you would prefer that it's set to 80 characters, for example:

"maximum_document_width": 80

Pre-formatted text tooltips

By default, when using a mouse, Rogallo will show any alt-text associated with some pre-formatted text when you hover the mouse cursor over the block of text.

If this feels too cluttered it can be turned off with the show_preformat_tooltips setting. Valid values are true and false, with true (show the tooltips) being the default.

"show_preformat_tooltips": true

Striped links

Rogallo provides a method of quick-jumping to links that is based around numeric labels that appear on the right in the viewer area. Placing the labels to the right helps keep a readable flow of text, but can possibly make it trickier to know which label matches which link.

To help with this you can turn on "striped links", which alternates the background colour of links to help make them stand out and connect with their labels. This is toggled using the Stripe Links (StripeLinks command, bound to F8 by default).

The setting itself is saved in the configuration file as the stripe_links configuration setting. It accepts true or false as valid values. It will be false (no stripes) by default:

"stripe_links": false

Theme

Rogallo has a number of themes available. You can select a theme using the Change Theme (ChangeTheme command, bound to F9 by default) command. The available themes include:

• atom-one-dark
• atom-one-light
• catppuccin-frappe
• catppuccin-latte
• catppuccin-macchiato
• catppuccin-mocha
• dracula
• flexoki
• gruvbox
• micro-cbm64
• monokai
• nord
• rose-pine
• rose-pine-dawn
• rose-pine-moon
• solarized-dark
• solarized-light
• terminal-amber
• terminal-green
• terminal-white
• textual-dark
• textual-light
• tokyo-night

Tip

You can also set the theme via the command line. This can be useful if you want to ensure that Rogallo runs up with a specific theme. Note that this also configures the theme for future runs of Rogallo.

Here's a sample of some of the themes:

User input editor

Rogallo supports using your choice of external text editor to edit user input. By default the input dialog will look to see if $VISUAL or $EDITOR are set in the environment and, if they are, you can press F3 when editing input to open your editor.

If you would prefer to set a specific editor for Rogallo itself, you can set external_editor in the configuration file. By default it is null (in which case it will look for $VISUAL and then $EDITOR):

"external_editor": null

Set it to the program to run to use that specific editor for Rogallo.