summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSheogorath2017-10-27 11:51:50 +0200
committerGitHub2017-10-27 11:51:50 +0200
commit94021e2d34390317406d55ecbc782c5ce345eef7 (patch)
tree1f07d41257299cfe774838134752c0297ee78539
parentbe5de239ea27a81b74cb252a162d909fd870ef21 (diff)
parent0864b06e0c1e78c417571320013de0dd13a467e9 (diff)
Merge pull request #574 from PeterDaveHello/README.md-Table-of-Contents
Add "Table of Contents" in README.md
-rw-r--r--README.md142
-rw-r--r--package.json4
2 files changed, 86 insertions, 60 deletions
diff --git a/README.md b/README.md
index 38dc52db..718f6863 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)
----
-
-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.
-
-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
----
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+# Table of Contents
+
+- [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)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# 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.
+
+* [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 files
----
+# 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 4c8dc562..04b969e3 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",