Merge pull request #574 from PeterDaveHello/README.md-Table-of-Contents

Add "Table of Contents" in README.md
This commit is contained in:
Sheogorath 2017-10-27 11:51:50 +02:00 committed by GitHub
commit 94021e2d34
2 changed files with 83 additions and 57 deletions

136
README.md
View file

@ -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)
---
<!-- 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
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
---
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
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

View file

@ -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",