A modern git based personal wiki that doesn't suck.
- Language independent
- Easy/zero configuration
- Modern UI
- Git based versioning
- Git based syncing (to GitHub)
- Intuitive hotkeys for better editing UX
- Prefetch internal wiki pages for faster response times
- Automatic Table Of Contents on pages (if you want)
- Spellcheck while you edit
- Live markdown preview
- Many more...
I couldn't find an open source wiki solution that I was happy with. They either looked super shitty, had terrible UX, or required a ton of configuration to get going (including sometimes installing new languages!). Exocortex aims to solve some these problems.
- Should be easy to run locally -
brew install && brew services
- Should only require a git repo to operate -
- Should have a modern interface that is a pleasure to work with (SPA React) - comes bundled with the binary.
- Should be backed up in the cloud so I never lose my hard work - thank you GitHub!
- Should only allow markdown for editing to reduce feature bloat -
$ brew tap spencercdixon/formulae $ brew install exocortex $ exo new my-first-wiki $ cd my-first-wiki && exo start $ open http://localhost:1234
- Must have
- Wiki must be a git repository
- Must have an
exocortex.jsonin your repo. (
exo initfor existing projects)
- Nothing else
new- creates a new directory with an
start- boots up the wiki server
init- creates a templated
exocortex.jsonfile based on sensible defaults
version- shows what version of exo binary you have installed
You shouldn't really need to worry about this. If you run
exo new to create a
exo init in an existing directory full of .md files these will get
pre-populated with sensible defaults.
syncInterval- time between remote pushes if remote is set up
repository- absolute path to where the repo for this wiki lives
title- base title for the wiki
remote- where to push the wiki to on the interval
branch- branch to use when pushing/pulling from remote
server.host- host wiki is located at
server.port- port to listen on
|Zen Mode||cmd + z||Eliminate all noise around the wiki for better editing|
|Help Mode||cmd + /|?||Show hot key help|
|Insert/Edit Mode||cmd + e|i||Turn whatever page you're viewing into 'edit' mode|
|Save Page||cmd + s||Save the page you're working on|
|Preview Mode||cmd + p||Turn whatever page you're viewing into 'edit' mode and split screen with a preview of what the MD will render to on the right|
If you want your pages to have a Table of Contents just add a
# tocsomewhere in the markdown
Exocortex is missing a lot of useful features that would enable it to go beyond just being a local personal wiki. I developed it while on Thanksgiving vacation primarily on planes so there was a limited feature set that I decided to prioritize. See below for a list of enhancements I'd like to add in the coming weeks:
- Prefetching of pages for better responsiveness
- User authentication
- Better UI customization/overrides
- Add ability to revert pages to previous commits
- Add ability to see diffs between commits
- Add boilerplates to
newcommand to get nice wiki structures fast
- Autocomplete on linked wiki pages
readme.md <-- file used for wiki homepage (not required) exocortex.json <-- wiki globals (required) .git <-- data store for the wiki (required)
That's it! The rest of your wiki can be structured however you'd like. In the future I'd like to include some boilerplates users can start from.
||returns global wiki settings|
||sets settings - only certain fields are allowed to be updated via API|
||search through wiki for a query|
||serve static images found in the wiki|
||retrieves content for this page|
||writes the file, commits|
||deletes the page|
||returns list of prefixes available|
||return the UI|
||Renders search results|
||Renders markdown of that path|
||Create a new page that doesn't exist in tree yet|
||Update a page that exists|
||TODO: See past revisions|
Why the name Exocortex?
Exocortex was shamelessly stolen from the book Pragmatic Thinking &
Andy Hunt talks a lot about the value of having an 'excortex' or personal wiki
to record your learning. I started documenting my own exocortex in
a year or so ago and this project aims to be a nice interface for that work.
Start On Boot
When using Exocortex as a service it will look at your
$HOME for a config file to use. This is how I have my machine setup:
$ ln -s ~/wiki/exocortex.json ~/exocortex.json <--- Sym link my main wiki's config to home $ brew services start exocortex <--- start the service
Note: I'm open to bug fixes and feature requests but I'm not sure how much free time I'll be able to commit to working on this. If there is a feature you aboslutely must have right away then feel free to fork!
There are a whole bunch of TODO's I'm working through located here. If you want to help contribute those are a good place to start.
Ensure you have the following installed:
Quick Start Development
Make bootstrap will build the UI, install the Go binary, create an empty example
wiki, and boot up that example wiki on
$ go get -u github.com/spencercdixon/exocortex $ cd $GOPATH/src/github.com/spencercdixon/exocortex $ make bootstrap
First make sure you have the backend running on port 1234
To work on the frontend you can run:
$ cd ui $ yarn install $ yarn start
This should boot up
http://localhost:3000 with a dev server that proxies to
localhost:1234 (where the API lives).
- Create a new git tag:
$ git tag -a v1.0.0 -m "v1.0.0 major milestone!" $ git push origin v1.0.0
- Export github token
$ export GITHUB_TOKEN=<repo access>
- Use goreleaser to release.
$ make release