Allwrite Docs

An incredibly fast documentation API powered by Google Drive written purely in Go.

This API connects with your Google Drive and provides RESTful endpoints which return the pages within Drive in a organized and usable format. With this API, beautiful (or ugly) user interfaces can be created and reused anywhere you need to display documentation online.

Features:

• Let anyone, technical or not, contribute to documentation.
• Full-text search.
• Auto-generating SSL via certbot.
• Transforms Google docs to clean markdown and html.
• Images are directly referenced from Google so you don't need to worry about image storage.
• No dependencies other than Postgres.
• URL structure builds itself based on the directory structure.
• Did I mention that it's crazy fast since pages are pre-cached?

Table of Contents

• Workflow
• Formatting
• Examples
• Themes
• Installation
• API
• Contributing
• CLI

Workflow

Give authors access to the activated folder using the typical means of doing so within Drive. Then authors can create pages and folders within the activated folder. Pages can have children infinitely deep by using directories. Pages and folders are both made public and ordered by using a special format in their page name.

|n| Page Title

The number between the two pipes (n) is what the menu is sorted by. It can be any number. If a page or directory does not have this format, it will not be public. This is useful when writing pages that should not yet be public (aka drafts).

Lastly, if zero is used (|0|), this is considered to be the landing page of the sub directory. If there is no directory, it is used as the default response, or "homepage". If a |0| is not provided for the root or sub directory, the return menu item will have a type of dir instead of file.

Formatting

Formatting within the document is done by using Google's wysiwyg, as usual. Allwrite then translates the content to well formatted html and markdown. Both the html and markdown formats are returned from the API so you may use which ever works best for you.

Formatting guide:

• Images just work. Plus they're hosted by Google for free!
• Unordered and ordered lists are treated as such.
• Colors, text alignment, and other frills will have no effect. Create an issue if you have a suggestion.
• Headers will be treated as such (<h1>, <h2>, and <h3>).
• Format code as you normally would (3 backticks followed by the language).

Examples

• stackahoy.io is going to use it.

Themes

• Spartan
• Make your own!

Installation

First, you should generate a OAuth 2.0 json file here. Select "other" for Application Type then place the client_secret.json file on the server you'll be running the API.

Head to your server and run the following to install or update Allwrite:

curl -L https://github.com/LevInteractive/allwrite-docs/blob/master/install.sh?raw=true | sh

If it's you're installing for the first time import the postgres schema:

curl -O https://raw.githubusercontent.com/LevInteractive/allwrite-docs/master/store/postgres/sql/pages.sql
psql < pages.sql

Finally, try to run the server in the foreground:

# Download the environmental variables. These need to available to the
# user/shell so allwrite can connect.
curl https://raw.githubusercontent.com/LevInteractive/allwrite-docs/master/creds.example.sh > creds

# Configure. Make sure these variables are correct.
vim creds

# Load the variables.
source creds

Start the server.

# Run the server. You'll eventually want to run this in the background and use
# something like nginx to create a reverse proxy.
allwrite s

Once you confirmed that it works, setup something like supervisord to run it for you. You can see an example configuration file for supervisord here

API

See response examples here.

Contributing

See docs for development here.

CLI

After installing, you'll have access to the CLI

$ allwrite-docs