Installation

Install:

• macOS
• Windows
• Snap
• Ubuntu
• Debian
• Fedora
• FreeBSD
• Arch Linux
• NixOS
• openSUSE
• WSL

Build:

• build on macOS
• build on Windows
• build on Ubuntu
• build on Debian
• build on Fedora
• build on Gentoo
• build on NixOS
• build on WSL
• build and run container

Configure:

• Appearance and themes
• Custom HTML Preview CSS
• Spell check
• Think vs. Sleep mode

Package for a new distribution or OS:

• download tarball

Look up:

• release
• change

Install a package

Install MindForger using a package.

If your operating system or distribution is not listed below, then check packages repository for Linux and Unix.

macOS

Install MindForger on macOS either using brew or by downloading .dmg.

Homebrew

Install MindForger using HomeBrew:

brew install mindforger

Disk iMaGe

Install MindForger using .dmg:

• download .dmg from GitHub releases

Install .dmg:

• Open/mount .dmg
• Drag and drop/copy mindforger from .dmg to Applications
• Run MindForger

MindForger creates copy of the documentation in your home directory (~/mindforger-repository) and opens it as default repository.

Windows

Install MindForger using installer.

• Download installer executable from https://github.com/dvorka/mindforger/releases (or try nightly build)
• Run installer.

WSL

Install Windows Subsystem for Linux (WSL) and check that you have Ubuntu 16.04 or newer:

lsb_release -a
  ...
  Release:        16.04
  Codename:       xenial

If not, then run sudo do-release-upgrade.

Install and start an X server for Windows like Xming.

Install MindForger from PPA. Add my PPA to Apt, trust GPG key, install MindForger and run it:

# add PPA to trusted repositories
sudo add-apt-repository ppa:ultradvorka/productivity

# update sources
sudo apt update

# install MindForger
sudo apt install mindforger

# run MindForger
DISPLAY=:0.0 mindforger

Snap

There are the following Snap distributions:

• SnapCraft.io package which uses strict confinement.
• Classic confinement package downloadable from GitHub Releases page.

Ubuntu

Install MindForger from PPA. Add my Lauchpad hosted PPA and install MindForger:

# add PPA to trusted repositories
sudo add-apt-repository ppa:ultradvorka/productivity

# update sources
sudo apt update

# install MindForger
sudo apt install mindforger

Debian

Install MindForger on Debian either by downloading .deb or from PPA.

Download .deb package for your Debian version from:

• GitHub Releases Assets section

To install MindForger from the PPA add my PPA for your Debian release version, trust GPG key and install MindForger - follow the instructions described in:

• http://www.mindforger.com/debian-ppa

For example Debian "bookworm":

# add PPA to APT sources:
echo "deb http://www.mindforger.com/debian-ppa/bookworm bookworm main" | sudo tee /etc/apt/sources.list.d/mindforger.list

# import PPA's GPG key
wget -qO - http://www.mindforger.com/gpgpubkey.txt | sudo apt-key add -

# update sources
sudo apt update

# install MindForger
sudo apt install mindforger

Fedora

Install MindForger on Fedora:

• download RPM from GitHub releases

Install RPM:

sudo dnf install mindforger-MAJOR.MINOR.REVISION.rpm

FreeBSD

Install MindForger on FreeBSD:

pkg install deskutils/mindforger
pkg install mindforger

(port commit)

Arch Linux

Install MindForger from Arch User Repository (AUR):

• https://aur.archlinux.org/packages/mindforger/

NixOS

Install MindForger package on NixOS:

nix-env -i mindforger

openSUSE

Install MindForger on openSUSE:

sudo zypper in opi
opi mindforger

Build from source code

Build MindForger from the source code.

Build on macOS

Build MindForger on macOS Sierra 10.12+.

Open Terminal and install/update Xcode command line tools:

xcode-select --install

Install/update HomeBrew package manager:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew doctor

Install build tools and dependencies:

brew install ccache

Download Qt from https://www.qt.io/download and in its online installer choose:

• Qt/Qt 5.x.x
  • latest available 5.x.x (Qt 5.9.9 or any newer Qt relese)
  • you can skip components like Android or iOS
• Developer and Designer Tools
  • Qt Creator
  • qmake
  • CMake
  • Qt Installer Framework

Once Qt is installed you can use ~/Qt/MaintennanceTool.app to add/remove Qt components.

Get source code:

git clone https://github.com/dvorka/mindforger.git
git submodule init
git submodule update

There are two ways how to build MindForger Disk iMaGe package:

1. either using scripts from MindForger's GitHub repository:
   • build/macos/mindforger-build.sh which creates MindForger executable
   • build/macos/dmg-package-build.sh which creates Disk iMaGe .dmg package on top of binary executable build made by mindforger-build.sh
2. or using the steps described below

Add dependencies to PATH:

• fix paths: username, Qt and its components versions might be different
• add PATH modifications below to your .bash_profile and/or .bashrc or .zshrc depending on your shell (configuration)
• don't forget to apply changes e.g. using . .bashr_profile

# clang
export PATH="/Users/username/Qt/5.x.x/clang_64/bin:${PATH}"
# cmake
export PATH="${PATH}:/Users/username/Qt/Tools/CMake/CMake.app/Contents/bin"
# installer
export PATH="${PATH}:/Users/username/Qt/Tools/QtInstallerFramework/3.2/bin"

Get source code:

git clone https://github.com/dvorka/mindforger.git
git submodule init
git submodule update

Build dependencies:

# build dependency: cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile sources from repository root directory:

qmake -r mindforger.pro
# consider adding -j parameter with the number of CPU cores to use e.g. make -j 8
make

Optionally install MindForger:

cd app && cp -rvf mindforger.app /Applications

Install documentation and stencils:

# clone MindForger documentation repository to home directory - location and directory name matters
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger either as application or using command line:

/Applications/mindforger.app/contents/MacOS/mindforger

Qt Creator development environment setup:

• start Qt Creator as application
• open project mindforger.pro
• configure project: clang kit, debug and release profiles
• menu Build/Run qmake
• menu Build/Build all
• menu Build/Run

Build .dmg distribution:

• start terminal session
• change to mindforger/build/macos
• run build/macos/dmg-package-build.sh
• check .dmg distro created in mindforger/app/mindforger.dmg

Build on Windows

Build MindForger on Microsoft Windows.

Install build tools:

• Install Microsoft Visual Studio IDE Community edition.
  • Choose Desktop development with C++ in installer.
• Install Qt and Qt Creator IDE
  • Qt version - choose latest 5.x.x Qt release available (must be Qt 5.9.5 or newer, suggested Qt 5.12.0 or newer)
  • Choose Qt > Qt 5.x.x > QMSVC 2017 64-bit
  • Choose Qt > Qt 5.x.x > Qt WebEngine
  • Choose Qt > Developer and Designer tools > Qt Creator
• Install cmake
• Install patch

Get source code from GitHub:

• Create directory where you want to build MindForger e.g. C:\Users\USER\mindforger-build

# create and change to build directory
C: | cd %HOMEPATH% | mkdir mindforger-build | cd mindforger-build
# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules
cd mindforger
git submodule init
git submodule update

• MindForger sources can be found in C:\Users\USER\mindforger-build\mindforger

Build dependencies:

• build cmark-gfm:

cd deps\cmark-gfm
mkdir build                                                                                                                                                                                                      
cd build                                                                                                                                                                                                         
cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_CONFIGURATION_TYPES=Debug;Release -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build . --config Release -- /m

Get default MindForger repository - documentation and examples (will be loaded on the first start):

# change to home directory
C: | cd %HOMEPATH%
# clone MindForger documentation
git clone https://github.com/dvorka/mindforger-repository.git

Build MindForger in Qt Creator:

1. Start Qt Creator
2. Open MindForger project:
   • Welcome/Open project
   • Choose C:\Users\USER\mindforger-build\mindforger\mindforger.pro as project file.
3. Choose kit:
   • Desktop Qt 5.x.x MSVC2017 64bit
4. Set build directory:
   • Set left toolbar's Projects/Build Settings/Build directory to C:\Users\USER\mindforger-build\mindforger
5. Set build configuration:
   • Set Projects/Build Settings/Edit build configuration choose Release
6. Build:
   • Menu Build/Build All

Run MindForger from Qt Creator:

• Menu Build\Run

Create installer:

• Install JRSoftware Inno Setup 5
• Prepare development environment. Change path according to your Qt installation
  • Run %QT_HOME%\5.x.x\msvc2017_64\bin\qtenv2.bat
• Gather dependencies
  • cd C:\Users\USER\mindforger-build\mindforger
  • %QT_HOME%\5.x.x\msvc2017_64\bin\windeployqt app\release\mindforger.exe --dir app\release\bin --no-compiler-runtime
• Build installer - update path to vcredist_x64.exe in the command below according to your setup:
  • cd C:\Users\USER\mindforger-build\mindforger
  • "C:\Program Files (x86)\Inno Setup 5\ISCC.exe" /Qp /DVcRedistPath="c:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Redist\MSVC\14.16.27012\vcredist_x64.exe" build\windows\installer\mindforger-setup.iss
• MindForger installer can be found in app\release\installer folder.

To create debug version of MindForger and executable replace debug with release in the steps above and use mindforger-setup-debug.iss installer configuration.

Build on WSL

Build MindForger on Windows Subsystem for Linux (WSL).

Install build tools:

sudo apt-get install build-essential zlib1g-dev libhunspell-dev libqt5webkit5-dev qttools5-dev-tools qt5-default ccache

Update gcc and g++ to version 5 (at least):

# adds the the test toolchain which includes gcc-5 and g++5 
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-5 g++-5
# substitute gcc-5 for gcc and g++-5 for g++ (current version)
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-5 60 --slave /usr/bin/g++ g++ /usr/bin/g++-5

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules
cd mindforger
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

# verify MindForger repository installation
ls mindforger-repository
  limbo  memory  mind  stencils

Run MindForger and start your XServer for Windows (e.g. Xming)

DISPLAY=:0.0 ./mindforger

Build on Ubuntu

Build MindForger on Ubuntu 16.04 or later.

Install package dependencies:

sudo apt-get install build-essential zlib1g-dev libhunspell-dev libqt5webkit5-dev qttools5-dev-tools qt5-default ccache cmake

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules
cd mindforger
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile sources and install MindForger from Git repository root directory:

qmake -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

See also mindforger/build/ubuntu/build-all-clean-system.sh

Build on Debian

Build MindForger on Debian 9 (stretch) or later.

Install package dependencies:

sudo apt-get install build-essential zlib1g-dev libhunspell-dev libqt5webkit5-dev qttools5-dev-tools ccache cmake debhelper

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build
# OPTIONAL step on certain Debian vesions: cmake -S . -B ./build
cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

Build on Fedora

Build MindForger on Fedora.

Install package dependencies:

sudo dnf install zlib-devel hunspell-devel qt-devel qt5-devel ccache

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules                                            
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake-qt5 -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

Build on Gentoo

Build MindForger on Gentoo:

Install package dependencies.

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules                                            
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake CONFIG+=mfwebengine -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

Build on NixOS

Build MindForger on Gentoo:

Install package dependencies.

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules                                            
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake CONFIG+=mfwebengine -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

Docker

Run MindForger in Docker container.

Build and run in container

Build Docker image and run MindForger in Docker container.

Build image:

mkdir mindforger

# download Dockerfile
curl https://raw.githubusercontent.com/dvorka/mindforger/master/build/docker/mindforger/Dockerfile > mindforger/Dockerfile

# build image
docker build -t mindforger:latest mindforger

Run container:

# allow access to X server (UNSECURE, but simple):
xhost +local:root

# run image
docker run -it --env="DISPLAY" --env="QT_X11_NO_MITSHM=1" \
    --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" mindforger:latest mindforger

# determine and remember container ID
docker ps -l -q > ~/.mindforger.docker

Run MindForger by starting container:

# start (stopped) container
docker start $(cat ~/.mindforger.docker)

Check also https://github.com/dvorka/mindforger/tree/master/build/docker for handy scripts.

Nightly builds

Nightly builds:

• macOS .dmg
• Windows installer
• tarball

Configure

MindForger can be configured either from UI:

• menu Workspace/Preferences or Mind/Adapt

... or using configuration file (while MindForger is NOT running):

• ~/.mindforger.md

Review .mindforger.md for configuration option details and descriptions.

Appearance and themes

Custom HTML Preview CSS

If you want to change color, font size, rendering of HTML preview, then it can be done using custom CSS.

You can either use your custom CSS - there is no UI for such change:

1. make sure MindForger is not running
2. download CSS you like https://github.com/dvorka/mindforger/tree/master/app/resources/qt/css (dark or light and choose Raw)
3. edit downloaded CSS file and change font size, ...
4. open $HOME/.mindforger.md and change path to your CSS, e.g.

...
* Markdown CSS theme: /home/USERNAME/my.css
...

This will ensure that CSS from given path will be loaded by HTML preview since the next time MindForger is started.

Wingman preferences

See Wingman LLM provider configuration

Spell check preferences

MindForger's spell check implementation is based on Hunspell.

Spell check configuration on Linux

Install Hunspell:

sudo apt install hunspell

Download vocabulary for your language from:

• https://extensions.openoffice.org/en/project/english-dictionaries-apache-openoffice

Install vocabulary:

• extract .oxt archive downloaded from the URL above to get .dict and .aff files
• determine Hunspell's vocabulary search path by running:

hunspell -D

• copy downloaded (.dict and .aff) vocabulary files to one of the directories on Hunspell's search path e.g. /usr/share/hunspell

Spell check configuration on Windows

Hunspell is included in MindForger executable, therefore it does not have to be installed.

Download vocabulary for your language from:

• https://extensions.openoffice.org/en/project/english-dictionaries-apache-openoffice

Install vocabulary:

• extract .oxt archive downloaded from the URL above to get .dict and .aff files
• copy downloaded (.dict and .aff) vocabulary files to one of the directories on Hunspell's search path:

C:\Users\<profile>\dictionaries
C:\Users\<profile>\Local Settings\dictionaries
C:\Users\<profile>\AppData\Local\dictionaries

Think vs. Sleep mode

MindForger can be either in thinking or sleeping mode:

• Thinking mode can be activated from menu Mind/Think and it's also indicated by the Thinking indicator in main window status bar.
  • MindForger runs background mind-related computations/tasks that can be CPU intensive
  • MindForger suggests relevant notes as you browse/read/write
  • MindForger named-entity recognition model is loaded and enabled
  • ...
• Sleeping mode can be activated from menu Mind/Sleep and it's also indicated by the Sleeping indicator in main window status bar.
  • MindForger runs no background mind-related computations/tasks i.e. it does not consume any extra CPU power and does not show any async information

Switch thinking/sleeping mode based on whether you need mind features for the particular repository or not - consider performance/CPU consumption vs features trade-off.

AA poler preferences