Skip to content

Latest commit

 

History

History
266 lines (210 loc) · 7.65 KB

readme.md

File metadata and controls

266 lines (210 loc) · 7.65 KB
Raw

Exocortex Logo

Exocortex

A modern git based personal wiki that doesn't suck.

Features

  • 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...

Why?

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.

First Principles

  1. Should be easy to run locally - brew install && brew services
  2. Should only require a git repo to operate - git init
  3. Should have a modern interface that is a pleasure to work with (SPA React) - comes bundled with the binary.
  4. Should be backed up in the cloud so I never lose my hard work - thank you GitHub!
  5. Should only allow markdown for editing to reduce feature bloat - .md ftw 😃

Installation

Go binaries can be downloaded directly from the releases page.

Homebrew

$ 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

User Requirements

  1. Must have git installed
  2. Wiki must be a git repository
  3. Must have an exocortex.json in your repo. (exo init for existing projects)
  4. Nothing else 💥

Commands

  • new - creates a new directory with an exocortex.json file
  • start - boots up the wiki server
  • init - creates a templated exocortex.json file based on sensible defaults
  • version - shows what version of exo binary you have installed

Configuration

You 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 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

Hotkeys

Hot keys gif

Action 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

Auto TOC

Tip

If you want your pages to have a Table of Contents just add a # toc somewhere in the markdown

Feature Roadmap

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 new command to get nice wiki structures fast
  • Autocomplete on linked wiki pages

Folder structure

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.

API Routes

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

UI Routes

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

Why the name Exocortex?

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.

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

Development/Contributing

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).

Releasing

  1. Create a new git tag:
$ git tag -a v1.0.0 -m "v1.0.0 major milestone!"
$ git push origin v1.0.0
  1. Export github token
$ export GITHUB_TOKEN=<repo access>
  1. Use goreleaser to release.
$ make release