diff --git a/README.md b/README.md index 38dc52d..718f686 100644 --- a/README.md +++ b/README.md @@ -14,34 +14,32 @@ Still in the early stage, feel free to fork or contribute to HackMD. Thanks for using! :smile: -[docker-hackmd](https://github.com/hackmdio/docker-hackmd) ---- + + +# Table of Contents -Before you go too far, here is the great docker repo for HackMD. -With docker, you can deploy a server in minutes without any downtime. +- [Browsers Requirement](#browsers-requirement) +- [Installation](#installation) + - [Getting started (Native install)](#getting-started-native-install) + - [Prerequisite](#prerequisite) + - [Instructions](#instructions) + - [Heroku Deployment](#heroku-deployment) + - [HackMD by docker container](#hackmd-by-docker-container) +- [Upgrade](#upgrade) + - [Native setup](#native-setup) +- [Configuration](#configuration) + - [Environment variables (will overwrite other server configs)](#environment-variables-will-overwrite-other-server-configs) + - [Application settings `config.json`](#application-settings-configjson) + - [Third-party integration api key settings](#third-party-integration-api-key-settings) + - [Third-party integration oauth callback urls](#third-party-integration-oauth-callback-urls) +- [Developer Notes](#developer-notes) + - [Structure](#structure) + - [Operational Transformation](#operational-transformation) +- [License](#license) -Heroku Deployment ---- + -You can quickly setup a sample heroku hackmd application by clicking the button below. - -[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy) - -[migration-to-0.5.0](https://github.com/hackmdio/migration-to-0.5.0) ---- - -We don't use LZString to compress socket.io data and DB data after version 0.5.0. -Please run the migration tool if you're upgrading from the old version. - -[migration-to-0.4.0](https://github.com/hackmdio/migration-to-0.4.0) ---- - -We've dropped MongoDB after version 0.4.0. -So here is the migration tool for you to transfer the old DB data to the new DB. -This tool is also used for official service. - -Browsers Requirement ---- +# Browsers Requirement - Chrome >= 47, Chrome for Android >= 47 - Safari >= 9, iOS Safari >= 8.4 @@ -50,15 +48,17 @@ Browsers Requirement - Opera >= 34, Opera Mini not supported - Android Browser >= 4.4 -Prerequisite ---- +# Installation + +## Getting started (Native install) + +### Prerequisite - Node.js 6.x or up (test up to 7.5.0) - Database (PostgreSQL, MySQL, MariaDB, SQLite, MSSQL) use charset `utf8` - npm (and its dependencies, especially [uWebSockets](https://github.com/uWebSockets/uWebSockets#nodejs-developers), [node-gyp](https://github.com/nodejs/node-gyp#installation)) -Get started ---- +### Instructions 1. Download a release and unzip or clone into a directory 2. Enter the directory and type `bin/setup`, which will install npm dependencies and create configs. The setup script is written in Bash, you would need bash as a prerequisite. @@ -67,8 +67,22 @@ Get started 5. Build front-end bundle by `npm run build` (use `npm run dev` if you are in development) 6. Run the server as you like (node, forever, pm2) -Upgrade guide ---- +## Heroku Deployment + +You can quickly setup a sample heroku hackmd application by clicking the button below. + +[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy) + +## HackMD by docker container + +[docker-hackmd](https://github.com/hackmdio/docker-hackmd) + +Before you go too far, here is the great docker repo for HackMD. +With docker, you can deploy a server in minutes without any downtime. + +# Upgrade + +## Native setup If you are upgrading HackMD from an older version, follow these steps: @@ -81,23 +95,18 @@ If you are upgrading HackMD from an older version, follow these steps: 6. Run `node_modules/.bin/sequelize db:migrate`, this step will migrate your db to the latest schema 7. Start your whole new server! -Structure ---- +* [migration-to-0.5.0](https://github.com/hackmdio/migration-to-0.5.0) -```text -hackmd/ -├── tmp/ --- temporary files -├── docs/ --- document files -├── lib/ --- server libraries -└── public/ --- client files - ├── css/ --- css styles - ├── js/ --- js scripts - ├── vendor/ --- vendor includes - └── views/ --- view templates -``` +We don't use LZString to compress socket.io data and DB data after version 0.5.0. +Please run the migration tool if you're upgrading from the old version. -Configuration files ---- +* [migration-to-0.4.0](https://github.com/hackmdio/migration-to-0.4.0) + +We've dropped MongoDB after version 0.4.0. +So here is the migration tool for you to transfer the old DB data to the new DB. +This tool is also used for official service. + +# Configuration There are some configs you need to change in the files below @@ -105,8 +114,7 @@ There are some configs you need to change in the files below ./config.json ----application settings ``` -Environment variables (will overwrite other server configs) ---- +## Environment variables (will overwrite other server configs) | variables | example values | description | | --------- | ------ | ----------- | @@ -160,8 +168,7 @@ Environment variables (will overwrite other server configs) | HMD_HSTS_MAX_AGE | `31536000` | max duration in seconds to tell clients to keep HSTS status (default is a year) | | HMD_HSTS_PRELOAD | `true` | whether to allow preloading of the site's HSTS status (e.g. into browsers) | -Application settings `config.json` ---- +## Application settings `config.json` | variables | example values | description | | --------- | ------ | ----------- | @@ -205,8 +212,7 @@ Application settings `config.json` | s3 | `{ "accessKeyId": "YOUR_S3_ACCESS_KEY_ID", "secretAccessKey": "YOUR_S3_ACCESS_KEY", "region": "YOUR_S3_REGION" }` | When `imageUploadType` be set to `s3`, you would also need to setup this key, check our [S3 Image Upload Guide](docs/guides/s3-image-upload.md) | | s3bucket | `YOUR_S3_BUCKET_NAME` | bucket name when `imageUploadType` is set to `s3` | -Third-party integration api key settings ---- +## Third-party integration api key settings | service | settings location | description | | ------- | --------- | ----------- | @@ -214,8 +220,7 @@ Third-party integration api key settings | imgur | environment variables or `config.json` | for image upload | | google drive(`google/apiKey`, `google/clientID`), dropbox(`dropbox/appKey`) | `config.json` | for export and import | -Third-party integration oauth callback urls ---- +## Third-party integration oauth callback urls | service | callback url (after the server url) | | ------- | --------- | @@ -226,14 +231,33 @@ Third-party integration oauth callback urls | dropbox | `/auth/dropbox/callback` | | google | `/auth/google/callback` | -Operational Transformation ---- +# Developer Notes + +## Structure + +```text +hackmd/ +├── tmp/ --- temporary files +├── docs/ --- document files +├── lib/ --- server libraries +└── public/ --- client files + ├── css/ --- css styles + ├── js/ --- js scripts + ├── vendor/ --- vendor includes + └── views/ --- view templates +``` + +## Operational Transformation From 0.3.2, we started supporting operational transformation. It makes concurrent editing safe and will not break up other users' operations. Additionally, now can show other clients' selections. See more at [http://operational-transformation.github.io/](http://operational-transformation.github.io/) + + +# License + **License under MIT.** [gitter-image]: https://badges.gitter.im/Join%20Chat.svg diff --git a/package.json b/package.json index 4c8dc56..04b969e 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,8 @@ "dev": "webpack --config webpack.config.js --progress --colors --watch", "build": "webpack --config webpack.production.js --progress --colors --bail", "postinstall": "bin/heroku", - "start": "node app.js" + "start": "node app.js", + "doctoc": "doctoc --title='# Table of Contents' README.md" }, "dependencies": { "Idle.Js": "git+https://github.com/shawnmclean/Idle.js", @@ -152,6 +153,7 @@ "babel-runtime": "^6.20.0", "copy-webpack-plugin": "^4.0.1", "css-loader": "^0.26.1", + "doctoc": "^1.3.0", "ejs-loader": "^0.3.0", "exports-loader": "^0.6.3", "expose-loader": "^0.7.1",