{"id":22799071,"url":"https://github.com/thomd/notebook","last_synced_at":"2026-04-02T02:50:52.411Z","repository":{"id":263066895,"uuid":"785295883","full_name":"thomd/notebook","owner":"thomd","description":"A simple wiki-like application to manage my personal notes as markdown files.","archived":false,"fork":false,"pushed_at":"2025-03-17T22:32:44.000Z","size":5919,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T23:33:06.061Z","etag":null,"topics":["docker","elasticsearch","markdown","python","react","wiki"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thomd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-11T15:44:13.000Z","updated_at":"2025-03-17T22:32:48.000Z","dependencies_parsed_at":"2024-11-15T23:26:20.430Z","dependency_job_id":"06d33da6-326a-459f-b5f3-22a604db0d09","html_url":"https://github.com/thomd/notebook","commit_stats":null,"previous_names":["thomd/notebook"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomd%2Fnotebook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomd%2Fnotebook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomd%2Fnotebook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomd%2Fnotebook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thomd","download_url":"https://codeload.github.com/thomd/notebook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246365651,"owners_count":20765549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","elasticsearch","markdown","python","react","wiki"],"created_at":"2024-12-12T07:07:49.930Z","updated_at":"2025-12-30T21:07:25.295Z","avatar_url":"https://github.com/thomd.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://github.com/thomd/notebook/raw/main/frontend/public/favicon.svg\" width=\"60\"\u003e\n\n# Notebook\n\n**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.\n\n**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_\").\n\n**Notebook** consists of four page types: an **index** page as an overview of all markdown pages, a **search** page, the nicely rendered markdown **pages** themself and an **editor** page to edit the markdown content.\n\nIndex Page:\n\n![screenshot of index page](https://raw.githubusercontent.com/thomd/notebook/refs/heads/images/index.png)\n\nRendered Markdown Page:\n\n![screenshot of page](https://raw.githubusercontent.com/thomd/notebook/refs/heads/images/page.png)\n\nEdit a Markdown Page:\n\n![screenshot of page edit](https://raw.githubusercontent.com/thomd/notebook/refs/heads/images/page-edit.png)\n\nSearch in all Markdown Pages:\n\n![screenshot of search](https://raw.githubusercontent.com/thomd/notebook/refs/heads/images/search.png)\n\n**Notebook** focuses on some **special features** to meet my needs:\n\n* Isolated editing of page headline sections (similar to Wikipedia) for ease of editing.\n* Extended markdown syntax: text highligting, tables, margin notes, mathematical expressions (via LaTeX) or internal page links.\n* Simple categorisation of pages on an overview page. Category-tiles can be positioned as required.\n* Page navigation reflecting the headline hierarchy.\n* Search within all pages.\n* Mark highly used pages as favorites.\n* Page interaction via keyboard.\n\n\u003e [!NOTE]\n\u003e Notebook was created to fit my personal needs. It might not fit your needs. It might not work properly on your machine.\n\n## Tech Stack\n\n**Notebook** is implemented as a **React** frontend for rendering and editing the markdown pages.\nPages are managed with a **Python** service which provides a REST API via **FastAPI** to read/write pages and commit/push pages to Github.\nAll pages are indexed and searchable via an **ElasticSearch** service.\n\n**Notebook** renders markdown pages leveraging the superb [remark](https://github.com/remarkjs) and [rehype](https://github.com/rehypejs) ecosystem.\n\nPart of the **Notebook** implementation is a set of special **plugins** like [remark-heading-lines](https://github.com/thomd/remark-heading-lines), [remark-wiki-link](https://github.com/thomd/remark-wiki-link), [rehype-textmarker](https://github.com/thomd/rehype-textmarker), [rehype-navigation](https://github.com/thomd/rehype-navigation) and [rehype-block](https://github.com/thomd/rehype-block).\n\n## Setup with Local Repository\n\nIf you don't want to push your markdown pages to a remote git repository and want to keep everything local.\n\n1. Create a local git repository folder for your markdown pages:\n\n        mkdir notebook-pages\n        (cd notebook-pages; git init)\n\n2. Clone this repository.\n\n        git clone https://github.com/thomd/notebook.git\n        cd notebook\n\n3. Add a record `127.0.0.1 notebook` into your local hosts file and flush DNS cache:\n\n        sudo vim /etc/hosts\n        sudo dscacheutil -flushcache\n\n4. Install locally-trusted SSL certificate using [mkcert](https://github.com/FiloSottile/mkcert):\n\n        mkcert -install\n        (cd frontend; mkcert notebook)\n\n5. Configure environment:\n\n        cp .env.example.local .env\n        vim .env\n\n6. Build application\n\n        docker compose build\n\n7. Start the application with\n\n        docker compose up -d\n        open https://notebook\n\n## Setup with Remote Repository\n\n1. Create a git repository on Github for your markdown pages like for example [notebook-example-pages](https://github.com/thomd/notebook-example-pages).\n\n2. Upload a public SSH key to Github using [gh-cli](https://cli.github.com/) (do not enter a passphrase for the key):\n\n        ssh-keygen -f ~/.ssh/notebook\n        gh ssh-key add ~/.ssh/notebook.pub -t notebook\n\n3. Clone this repository.\n\n4. Add a record `127.0.0.1 notebook` into your local hosts file and flush DNS cache:\n\n        sudo vim /etc/hosts\n        sudo dscacheutil -flushcache\n\n5. Install locally-trusted SSL certificate using [mkcert](https://github.com/FiloSottile/mkcert):\n\n        mkcert -install\n        (cd frontend; mkcert notebook)\n\n6. Configure environment\n\n        cp .env.example.remote .env\n        vim .env\n\n7. Build application\n\n        docker compose build\n\n8. Start the application with\n\n        docker compose up -d\n        open https://notebook\n\n## Usage\n\n### Keyboard Shortcuts\n\n* Show help with \u003ckbd\u003eH\u003c/kbd\u003e\n* Edit page with \u003ckbd\u003eE\u003c/kbd\u003e\n* Delete page with \u003ckbd\u003eD\u003c/kbd\u003e\n* Scroll page to top with \u003ckbd\u003eQ\u003c/kbd\u003e\n* Scroll page to bottom with \u003ckbd\u003eW\u003c/kbd\u003e\n* Open index page with \u003ckbd\u003eI\u003c/kbd\u003e or \u003ckbd\u003eesc\u003c/kbd\u003e\n* Toggle page navigation with \u003ckbd\u003eN\u003c/kbd\u003e\n* Search with \u003ckbd\u003eS\u003c/kbd\u003e or \u003ckbd\u003e/\u003c/kbd\u003e\n\n### Markdown\n\nSee [markdown pages](https://github.com/thomd/notebook-example-pages/tree/main/pages) of the example-pages repository for some explanatory examples.\n\n## Development\n\nFollow development instructions in [backend](./backend/README.md) and [frontend](./frontend/README.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomd%2Fnotebook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomd%2Fnotebook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomd%2Fnotebook/lists"}