adji
adji is a recursive acronym for Adji’s a Decisive and Joyful
Internet browser
adji is a simple, decisive and distraction free web browser
using GTK+ 3, GLib and WebKit2GTK+. This web browser takes
inspiration from other web browsers like surf , lariza
and vimb .
Download
adji 0.1.9
(33kb) (2023-03-09)
Setting up an environment
To optimize the usage of adji, it is recommended to configure
certain environment variables, ideally by exporting them through
your ~/.profile file. Here is an example of the
variable values that I prefer:
# setup adji browser config
export ADJI_ACCEPTED_LANGUAGES="en_US"
export ADJI_COOKIE_FILE="$XDG_CACHE_HOME/adji/cookies"
export ADJI_DEFAULT_FONT="Source Code Pro"
export ADJI_DEFAULT_FONT_SIZE="16"
export ADJI_DOWNLOAD_DIR="$HOME/downloads"
export ADJI_HISTORY_FILE="$XDG_CACHE_HOME/adji/history"
export ADJI_MONOSPACE_FONT="Source Code Pro"
export ADJI_SANS_SERIF_FONT="Liberation Sans"
export ADJI_SERIF_FONT="Liberation Serif"
export ADJI_SE_URI_FORMAT="https://ddg.gg?q=%s"
export ADJI_STATE_FILE="$XDG_CACHE_HOME/adji/state"
Manual
ADJI(1) General Commands Manual ADJI(1)
NAME
adji - Adji's a Decisive and Joyful Internet browser
SYNOPSIS
adji [-I] [URI...]
DESCRIPTION
adji is a simple, decisive and distraction free web browser using GTK+
3, GLib and WebKit2GTK+. This web browser takes inspiration from other
web browsers like surf(1), lariza(1) and vimb(1).
OPTIONS
Along with the standard arguments for GTK+ 3 (see gtk-options(7)), adji
is equipped with the following options:
-I Implements an independent instance without any ipc
configuration.
If no URI are provided, the value of the enviornment variable
ADJI_HOME_URI will be opened which defaults to “about:blank”.
Otherwise, any number of URIs may follow these options.
ENVIRONMENT
adji recognizes the following environment variables, in addition to the
standard variables of GTK+ 3:
ADJI_ACCEPTED_LANGUAGES
When sending an HTTP request, WebKit populates the “Accepted-
Language” header based on the provided list of languages, which
can be comma-separated (e.g. “en_US,en_AU”). If no languages are
specified, WebKit will use en_US as the default.
ADJI_COOKIE_FILE
By providing a path to a cookie file, adji will provide a method
of sharing cookies between sessions and instances.
ADJI_DEFAULT_FONT
Provides a method for specifying the default font inside the web
view of adji. If no default font is specified, WebKit will use
sans-serif as the default.
ADJI_DEFAULT_FONT_SIZE
Provides a method for specifying the default font size inside
the web view of adji. If no default font size is specified,
WebKit will use 16 as the default.
ADJI_DISABLE_AUTO_LOAD_IMAGES
For a faster, or perhaps a more secure way of browsing the web,
setting this variable provides a method of preventing images
from loading automatically.
ADJI_DOWNLOAD_DIR
This variable allows you to specify the directory to where all
downloads are stored according to your preference. By default
all downloads are stored at /var/tmp.
ADJI_ENABLE_CONSOLE_TO_STDOUT
Output that is printed to the web view console can be copied to
STDOUT setting this variable.
ADJI_ENABLE_SMOOTH_SCROLLING
By default adji disables the janky and annoying “smooth
scrolling”. If you for some reason like it, setting this
variable will enable it.
ADJI_FIFO_NAME
adji implements IPC configurations using named pipes in the file
system. According to XDG standards, the files for these named
pipes are stored as
/var/run/user/$UID/adji_$ADJI_FIFO_NAME.fifo.
The $UID refers to the id of the user running adji.
$ADJI_FIFO_NAME refers to the value of this variable, which
defaults to default. By specifying this variable, parallel IPC
configurations can be used. Be sure to also specify the
$ADJI_STATE_FILE accordingly. If you do not, the IPC instances
will conflict and overwrite the states of each other.
ADJI_HISTORY_FILE
When set, adji will store each visited URI to the file
specified.
ADJI_HOME_URI
The URI that will be opened in new tabs if nothing else is
specified. Defaults to about:blank.
ADJI_MONOSPACE_FONT
Provides a method for specifying the monospace font inside the
web view of adji. If no monospace font is specified, WebKit
will use monospace as the default.
ADJI_PROXY_IGNORE
When specifying a proxy URI, adji will send every HTTP requests
through that URI. To exclude traffic to certain hosts from being
sent through the specified proxy URI, this variable can be used
to provide a comma-separated list of hosts to be ignored (e.g.
“127.0.0.1,noxz.tech”).
ADJI_PROXY_URI
By specifying a proxy URI, adji will send every HTTP requests
through that URI. As an example a socks proxy for tor can be
specified in this way “socks://127.0.0.1:9050”.
ADJI_SANS_SERIF_FONT
Provides a method for specifying the sans-serif font inside the
web view of adji. If no sans-serif font is specified, WebKit
will use sans-serif as the default.
ADJI_SERIF_FONT
Provides a method for specifying the serif font inside the web
view of adji. If no serif font is specified, WebKit will use
serif as the default.
ADJI_SE_URI_FORMAT
If an entry cannot be resolved as either a URI or a file path, a
web search will be performed. To define the method of
perforating this web search, a format can be utilized in the
following manner, using http://ddg.gg as an example:
“https://ddg.gg?q=%s”. One, and only one, string reference (%s)
must be specified. The default value is https://ddg.gg?q=%s.
ADJI_STATE_FILE
By specifying a path to a state file, adji will save the state
of open tabs for next time the program is run. Each time a tab
is moved, updated or otherwise changed, the state of open tabs
will be saved as a list of URIs. It is important to avoid using
the same state file for multiple IPC configurations, as they
will conflict and overwrite each other.
ADJI_VERBOSE
If set, this feature is employed by we_redirect.so to verbosely
output to STDERR which redirections are being.
ADJI_USER_AGENT
By default, adji uses WebKit's default value for the user agent
string. This variable can be utilized to specify an alternative
user agent to the default one.
ADJI_ZOOM_LEVEL
This variable can be utilized to set the zoom level of WebKit's
viewports. The default value is 1.0.
FILES
These paths will be constructed using XDG variables.
~/.config/adji/redirect
Redirect rules used by we_redirect.so. See the WEB EXTENSION
section.
~/.config/adji/exthandler
adji has a built-in mechanism for externally handling URIs. You
can use the file specified by the path to define how these URIs
should be handled in a customized manner. A system call passes
the URI as the first parameter.
~/.config/adji/scripts
Directory to store user scripts (JavaScript).
~/.config/adji/styles
Directory to store user style sheets (CSS).
~/.config/adji/web_extensions
Directory where WebKit will search for web extensions.
~/.cache/adji
~/.cache/webkitgtk
~/.local/share/webkitgtk
WebKitGTK will store its caches and local storage data in these
directories. It is recommended to periodically clean these
directories or mount them as some sort of volatile storage.
USAGE
Entry
Entry refers to the entry/location/command bar at the bottom of the
window.
Mod1-h Navigate the caret to the left in the entry.
Mod1-l Navigate the caret to the right in the entry.
Enter/Return
The entered command or URI is resolved as appropriate. If no
resolution is found, the entry is reverted back to its original
value. Escape The entry is reverted back to its original value.
Tab bar
Button1
When a tab is clicked, the corresponding pair of web view and
entry will be made visible
Button2
Clicking on a tab using the scroll wheel will close the pair of
view and entry represented by that tab
Scroll wheel
While hovering over the tab bar, scrolling the scroll wheel will
allow you to move through tabs in the same direction as your
scroll.
Download bar
The download bar remains hidden until a download is initiated. As the
download progresses, the progress is shown and updated. Each download
is represented by a button that can be clicked. During an active
download, clicking the button will abort the download and remove the
button. Once the download is complete, the button will simply be
removed when clicked.
Web view
Escape Stops the web rendering.
Button2
Opens a hovered URI in a new tab.
Button8
Go back in history.
Button9
Go forward in history.
Mod1-[Scroll Wheel]
The zoom level of the current web view can be adjusted by
scrolling while holding down the Mod1 key.
Global keyboard commands
Mod1-Ctrl-Shift-j
Move the current tab to the left (further down in the stack)
within the tab bar.
Mod1-Ctrl-Shift-K
Move the current tab to the right (further up in the stack)
within the tab bar.
Mod1-Ctrl-j
Switch to the previous tab (the one to the left of the current
one).
Mod1-Ctrl-k
Switch to the next tab (the one to the right of the current
one).
Mod1-[1..n]
Switch to the nth tab.
Mod1-q Close the current tab.
Mod1-w Go the specified home page.
Mod1-t Open the specified home page within a new tab.
Mod1-r Reload the page, bypassing the cache.
Mod1-o Focus the entry bar for input.
Mod1-/ Initiate an in-page search.
Mod1-n Perform a forward search within the context of the in-page
search.
Mod1-Shift-n
Perform a backwards search within the context of the in-page
search.
Mod1-b Toggle the visibility of the tab bar.
Mod1-Shift-h
Go back in history.
Mod1-Shift-l
Go forward in history.
Mod1-s Toggle JavaScript functionality on or off.
Mod1-c Toggle the TLS error policy between fail or ignore.
Mod1-h Move/scroll towards the left on the page.
Mod1-l Move/scroll towards the right on the page.
Mod1-j Move/scroll towards the bottom of the page.
Mod1-k Move/scroll towards the top of the page.
Mod1-Shift-g
Go to the bottom of the page.
Mod1-g Go to the top of the page.
Mod1-p Open the print dialog.
Entry commands
Commands can be executed from the entry using a proceeding “:”. adji
accepts two types of commands.
q If applicable, the program saves its state before quitting.
/ To initiate an in-page search for a specific phrase, such as
“banana”, you would enter the succeeding phrase in the format of
:/banana.
User scripts
Upon successful loading of a page, the directory ~/.config/adji/scripts
is scanned, and every file with the “.js” extension is executed as a
JavaScript file within the context of the loaded page.
User styles
Upon successful loading of a page, the directory ~/.config/adji/styles
is scanned, and every file with the “.css” extension is injected as a
style sheet within the context of the loaded page. These style sheets
can be utilized to customize the appearance of web pages according to
your preferences.
WEB EXTENSION
we_redirect.so
To specify redirect rules in the redirect file, you should use
the following format: /pattern/destination/. Each rule should
be written on a single line, and an arbitrary separator should
be used to initialize each rule. This separator can be any
character except for the “#” symbol, which is used for line
comments. The pattern can be any regular expression pattern that
matches a URI request. The destination can be left empty, or it
can contain a replacement pattern that references regex groups
from the pattern. If the destination is empty, the request will
be terminated and act as a URI block.
Regular expressions in terms of syntax and semantics are akin to
Perl regular expressions.
EXAMPLES
adji -I
This command launches an independent adji instance without any
IPC configuration. It will not load or save any states.
However, if certain environment variables like ADJI_HISTORY_FILE
and ADJI_COOKIE_FILE are defined, this instance will use them.
Therefore, it cannot be considered completely isolated.
To make such an instance more isolated the variables
ADJI_HISTORY_FILE, ADJI_COOKIE_FILE, XDG_CACHE_HOME, and
XDG_DATA_HOME should be set to the value “/dev/null” before
executing the command.
ADJI_PROXY_URI=socks://127.0.0.1:9050 adji -I
This command launches an independent adji instance without any
IPC configuration. It routes every HTTP request through a
designated proxy URI, specifically a tor socks proxy in this
case. It will not load or save any states.
However, to enhance privacy and isolation of this instance,
measures must be taken to prevent data leakage through cookies
or other sources. Additionally, consider using a more privacy-
focused web browser.
KNOWN ISSUES
Double-clicking on a tab grabs the focus and prevents global key
commands from functioning. This issue could be addressed by focusing
the web view upon tab click events. However, as it is a minor problem
and only present in a mouse workflow, such a solution has not been
implemented.
AUTHOR
Chris Noxz <chris@noxz.tech>
COPYRIGHT
Copyright © 2023 Chris Noxz.
License: GPLv3+
GNU GPL version 3 or later
<https://www.gnu.org/licenses/licenses.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
adji-0.1.9 ADJI(1)
Installation
Edit config.mk to match your local setup (adji is installed into
the /usr/local namespace by default), then simply enter the
following command to install (if necessary as root):
get source here .
