Notebook

Notebook is a simple, minimalistic wiki-like web application to manage my personal notes as markdown files and store them in a private git repository on Github.

Notebook consists of four page types: an index page as an overview of all pages, a search page, the pages itself and an editor page to edit its content:

Index

Page

Edit Page

Search

Notebook was created with the intention of running it locally (to avoid hosting and user management). Markdown files are stored in a local or remote git repository ("git as database") which allows to read and edit them in Github.

Notebook is implemented as a React frontend for rendering and editing the markdown pages. Pages are managed with a Python service which provides a REST API via FastAPI to read/write pages and commit/push pages to Github. All pages are indexed and searchable via an ElasticSearch service.

Notebook focuses on some special features to meet my needs:

• Isolated editing of page headline sections (similar to Wikipedia) for ease of editing.
• Extended markdown syntax: text highligting, tables, margin notes, mathematical expressions (via LaTeX) or internal page links.
• Simple categorisation of pages on an overview page. Category-tiles can be positioned as required.
• Page navigation reflecting the headline hierarchy.
• Search within all pages.
• Mark highly used pages as favorites.
• Page interaction via keyboard.

Notebook renders markdown pages leveraging the superb remark and rehype ecosystem.

Part of the Notebook implementation is a set of special plugins like remark-heading-lines, remark-wiki-link, rehype-textmarker, rehype-navigation and rehype-block.

Note

Notebook was created to fit my personal needs. It might not fit your needs. It might not work properly on your machine.

Setup with Local Repository

If you don't want to push your notebook pages to a remote git repository and want to keep everything local.

1. Create a local git repository folder for your notebook pages:

    mkdir notebook-pages
    (cd notebook-pages; git init)
   

2. Clone this repository.

    git clone https://github.com/thomd/notebook.git
    cd notebook
   

3. Add a record 127.0.0.1 notebook into your local hosts file and flush DNS cache:

    sudo vim /etc/hosts
    sudo dscacheutil -flushcache
   

4. Install locally-trusted SSL certificate using mkcert:

    mkcert -install
    (cd frontend; mkcert notebook)
   

5. Configure environment:

    cp .env.example.local .env
    vim .env
   

6. Build application

    docker compose build
   

7. Start the application with

    docker compose up -d
    open https://notebook
   

Setup with Remote Repository

1. Create a git repository on Github for your notebook pages like for example notebook-example-pages.

2. Upload a public SSH key to Github using gh-cli (do not enter a passphrase for the key):

    ssh-keygen -f ~/.ssh/notebook
    gh ssh-key add ~/.ssh/notebook.pub -t notebook
   

3. Clone this repository.

4. Add a record 127.0.0.1 notebook into your local hosts file and flush DNS cache:

    sudo vim /etc/hosts
    sudo dscacheutil -flushcache
   

5. Install locally-trusted SSL certificate using mkcert:

    mkcert -install
    (cd frontend; mkcert notebook)
   

6. Configure environment

    cp .env.example.remote .env
    vim .env
   

7. Build application

    docker compose build
   

8. Start the application with

    docker compose up -d
    open https://notebook
   

Usage

Keyboard Shortcuts

• Show help with H
• Edit page with E
• Delete page with D
• Scroll page to top with Q
• Scroll page to bottom with W
• Open index page with I or esc
• Toggle page navigation with N
• Search with S or /

Markdown

See markdown pages of the example-pages repository for some explanatory examples.

Development

Follow development instructions in backend and frontend.