From 4ebda60165d7fc272302ed86386ed4fe0badb7a7 Mon Sep 17 00:00:00 2001 From: Peter Dave Hello Date: Sun, 8 Oct 2017 19:37:20 +0800 Subject: Reorganize README.md structure, cc #574 --- README.md | 117 +++++++++++++++++++++++++++++++------------------------------- 1 file changed, 58 insertions(+), 59 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 78d3e352..6012b35a 100644 --- a/README.md +++ b/README.md @@ -14,34 +14,7 @@ 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 ---- +# Browsers Requirement - Chrome >= 47, Chrome for Android >= 47 - Safari >= 9, iOS Safari >= 8.4 @@ -50,15 +23,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 +42,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 +70,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 +89,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 | | --------- | ------ | ----------- | @@ -155,8 +138,7 @@ Environment variables (will overwrite other server configs) | HMD_S3_REGION | `ap-northeast-1` | AWS S3 region | | HMD_S3_BUCKET | no example | AWS S3 bucket name | -Application settings `config.json` ---- +## Application settings `config.json` | variables | example values | description | | --------- | ------ | ----------- | @@ -199,8 +181,7 @@ Application settings `config.json` | s3 | `{ "accessKeyId": "YOUR_S3_ACCESS_KEY_ID", "secretAccessKey": "YOUR_S3_ACCESS_KEY", "region": "YOUR_S3_REGION" }` | When `imageUploadType` be setted 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 | | ------- | --------- | ----------- | @@ -208,8 +189,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) | | ------- | --------- | @@ -220,14 +200,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 -- cgit v1.2.3