A modern git based personal wiki that doesn't suck.
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.
brew install && brew services
git init
.md
ftw :smiley:Go binaries can be downloaded directly from the releases page.
$ brew tap spencercdixon/formulae
$ brew install exocortex
$ exo new my-first-wiki
$ cd my-first-wiki && exo start
$ open http://localhost:1234
Starting exocortex as a service on boot
git
installedexocortex.json
in your repo. (exo init
for existing projects)new
- creates a new directory with an exocortex.json
filestart
- boots up the wiki serverinit
- creates a templated exocortex.json
file based on sensible defaultsversion
- shows what version of exo binary you have installedYou shouldn't really need to worry about this. If you run exo new
to create a
wiki or 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 uprepository
- absolute path to where the repo for this wiki livestitle
- base title for the wikiremote
- where to push the wiki to on the intervalbranch
- branch to use when pushing/pulling from remoteserver.host
- host wiki is located atserver.port
- port to listen onAction | Shortcut | Description |
---|---|---|
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 |
Tip
If you want your pages to have a Table of Contents just add a
# toc
somewhere 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:
new
command to get nice wiki structures fastreadme.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.
Method | Path | Description |
---|---|---|
GET | /api/settings |
returns global wiki settings |
POST | /api/settings |
sets settings - only certain fields are allowed to be updated via API |
POST | /api/search |
search through wiki for a query |
POST | /api/images/:path-to-image |
serve static images found in the wiki |
GET | /api/wiki/:page-name |
retrieves content for this page |
POST | /api/wiki/:page-name |
writes the file, commits |
DELETE | /api/wiki/:page-name |
deletes the page |
GET | /api/ |
returns list of prefixes available |
GET | /* |
return the UI |
Route | Description |
---|---|
/search |
Renders search results |
/wiki/:page-name |
Renders markdown of that path |
/wiki/new/:page-name |
Create a new page that doesn't exist in tree yet |
/wiki/edit/:page-name |
Update a page that exists |
/wiki/revisions/:page-name |
TODO: See past revisions |
Exocortex was shamelessly stolen from the book Pragmatic Thinking &
Learning.
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 .md
files
a year or so ago and this project aims to be a nice interface for that work.
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:
go 1.9
node >6
yarn
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 localhost:1234
.
$ go get -u github.com/spencercdixon/exocortex
$ cd $GOPATH/src/github.com/spencercdixon/exocortex
$ make bootstrap
Frontend
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).
$ git tag -a v1.0.0 -m "v1.0.0 major milestone!"
$ git push origin v1.0.0
$ export GITHUB_TOKEN=<repo access>
$ make release