GitHub Readme.md
HackMD lets you create realtime collaborative markdown notes on all platforms. Inspired by Hackpad, with more focus on speed and flexibility. Still in the early stage, feel free to fork or contribute to HackMD.
Thanks for using! π
utf8
bin/setup
, which will install npm dependencies and create configs. The setup script is written in Bash, you would need bash as a prerequisite.npm run build
(use npm run dev
if you are in development)You can quickly setup a sample heroku hackmd application by clicking the button below.
Debian-based version:
Alpine-based version:
The easiest way to setup HackMD using docker are using the following three commands:
git clone https://github.com/hackmdio/docker-hackmd.git
cd docker-hackmd
docker-compose up
Read more about it in the docker repositoryβ¦
If you are upgrading HackMD from an older version, follow these steps:
git pull
or do whatever that updates the filesnpm install
to update dependenciesnpm run build
(use npm run dev
if you are in development).sequelizerc
, change the value of the variable url
with your db connection string
For example: postgres://username:password@localhost:5432/hackmd
node_modules/.bin/sequelize db:migrate
, this step will migrate your db to the latest schemaWe 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.
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.
There are some configs you need to change in the files below
./config.json ----application settings
production
or development
set current environment (will apply corresponding settings in the config.json
)
DEBUG
true
or false
set debug mode, show more logs
HMD_DOMAIN
hackmd.io
domain name
HMD_URL_PATH
hackmd
sub url path, like www.example.com/<URL_PATH>
HMD_PORT
80
web app port
HMD_ALLOW_ORIGIN
localhost, hackmd.io
domain name whitelist (use comma to separate)
HMD_PROTOCOL_USESSL
true
or false
set to use ssl protocol for resources path (only applied when domain is set)
HMD_URL_ADDPORT
true
or false
set to add port on callback url (port 80 or 443 won't applied) (only applied when domain is set)
HMD_USECDN
true
or false
set to use CDN resources or not (default is true
)
HMD_ALLOW_ANONYMOUS
true
or false
set to allow anonymous usage (default is true
)
HMD_ALLOW_FREEURL
true
or false
set to allow new note by accessing not exist note url
HMD_DEFAULT_PERMISSION
freely
, editable
, limited
, locked
or private
set notes default permission (only applied on signed users)
HMD_DB_URL
mysql://localhost:3306/database
set the db url
HMD_FACEBOOK_CLIENTID
no example
Facebook API client id
HMD_FACEBOOK_CLIENTSECRET
no example
Facebook API client secret
HMD_TWITTER_CONSUMERKEY
no example
Twitter API consumer key
HMD_TWITTER_CONSUMERSECRET
no example
Twitter API consumer secret
HMD_GITHUB_CLIENTID
no example
GitHub API client id
HMD_GITHUB_CLIENTSECRET
no example
GitHub API client secret
HMD_GITLAB_SCOPE
read_user
or api
GitLab API requested scope (default is api
) (gitlab snippet import/export need api
scope)
HMD_GITLAB_BASEURL
no example
GitLab authentication endpoint, set to use other endpoint than GitLab.com (optional)
HMD_GITLAB_CLIENTID
no example
GitLab API client id
HMD_GITLAB_CLIENTSECRET
no example
GitLab API client secret
HMD_MATTERMOST_BASEURL
no example
Mattermost authentication endpoint
HMD_MATTERMOST_CLIENTID
no example
Mattermost API client id
HMD_MATTERMOST_CLIENTSECRET
no example
Mattermost API client secret
HMD_DROPBOX_CLIENTID
no example
Dropbox API client id
HMD_DROPBOX_CLIENTSECRET
no example
Dropbox API client secret
HMD_GOOGLE_CLIENTID
no example
Google API client id
HMD_GOOGLE_CLIENTSECRET
no example
Google API client secret
HMD_LDAP_URL
ldap://example.com
url of LDAP server
HMD_LDAP_BINDDN
no example
bindDn for LDAP access
HMD_LDAP_BINDCREDENTIALS
no example
bindCredentials for LDAP access
HMD_LDAP_TOKENSECRET
supersecretkey
secret used for generating access/refresh tokens
HMD_LDAP_SEARCHBASE
o=users,dc=example,dc=com
LDAP directory to begin search from
HMD_LDAP_SEARCHFILTER
(uid={{username}})
LDAP filter to search with
HMD_LDAP_SEARCHATTRIBUTES
no example
LDAP attributes to search with
HMD_LDAP_TLS_CA
server-cert.pem, root.pem
Root CA for LDAP TLS in PEM format (use comma to separate)
HMD_LDAP_PROVIDERNAME
My institution
Optional name to be displayed at login form indicating the LDAP provider
HMD_IMGUR_CLIENTID
no example
Imgur API client id
HMD_EMAIL
true
or false
set to allow email signin
HMD_ALLOW_PDF_EXPORT
true
or false
Enable or disable PDF exports
HMD_ALLOW_EMAIL_REGISTER
true
or false
set to allow email register (only applied when email is set, default is true
)
HMD_IMAGE_UPLOAD_TYPE
imgur
, s3
or filesystem
Where to upload image. For S3, see our S3 Image Upload Guide
HMD_S3_ACCESS_KEY_ID
no example
AWS access key id
HMD_S3_SECRET_ACCESS_KEY
no example
AWS secret key
HMD_S3_REGION
ap-northeast-1
AWS S3 region
HMD_S3_BUCKET
no example
AWS S3 bucket name
HMD_HSTS_ENABLE
true
set to enable HSTS if HTTPS is also enabled (default is true
)
HMD_HSTS_INCLUDE_SUBDOMAINS
true
set to include subdomains in HSTS (default is true
)
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)
config.json
true
or false
set debug mode, show more logs
domain
localhost
domain name
urlpath
hackmd
sub url path, like www.example.com/<urlpath>
port
80
web app port
alloworigin
['localhost']
domain name whitelist
usessl
true
or false
set to use ssl server (if true will auto turn on protocolusessl
)
hsts
{"enable": "true", "maxAgeSeconds": "31536000", "includeSubdomains": "true", "preload": "true"}
HSTS options to use with HTTPS (default is the example value, max age is a year)
protocolusessl
true
or false
set to use ssl protocol for resources path (only applied when domain is set)
urladdport
true
or false
set to add port on callback url (port 80 or 443 won't applied) (only applied when domain is set)
usecdn
true
or false
set to use CDN resources or not (default is true
)
allowanonymous
true
or false
set to allow anonymous usage (default is true
)
allowfreeurl
true
or false
set to allow new note by accessing not exist note url
defaultpermission
freely
, editable
, limited
, locked
, protected
or private
set notes default permission (only applied on signed users)
dburl
mysql://localhost:3306/database
set the db url, if set this variable then below db config won't be applied
db
{ "dialect": "sqlite", "storage": "./db.hackmd.sqlite" }
set the db configs, see more here
sslkeypath
./cert/client.key
ssl key path (only need when you set usessl)
sslcertpath
./cert/hackmd_io.crt
ssl cert path (only need when you set usessl)
sslcapath
['./cert/COMODORSAAddTrustCA.crt']
ssl ca chain (only need when you set usessl)
dhparampath
./cert/dhparam.pem
ssl dhparam path (only need when you set usessl)
tmppath
./tmp/
temp directory path
defaultnotepath
./public/default.md
default note file path
docspath
./public/docs
docs directory path
indexpath
./public/views/index.ejs
index template file path
hackmdpath
./public/views/hackmd.ejs
hackmd template file path
errorpath
./public/views/error.ejs
error template file path
prettypath
./public/views/pretty.ejs
pretty template file path
slidepath
./public/views/slide.hbs
slide template file path
sessionname
connect.sid
cookie session name
sessionsecret
secret
cookie session secret
sessionlife
14 * 24 * 60 * 60 * 1000
cookie session life
staticcachetime
1 * 24 * 60 * 60 * 1000
static file cache time
heartbeatinterval
5000
socket.io heartbeat interval
heartbeattimeout
10000
socket.io heartbeat timeout
documentmaxlength
100000
note max length
email
true
or false
set to allow email signin
allowemailregister
true
or false
set to allow email register (only applied when email is set, default is true
)
imageUploadType
imgur
(default), s3
or filesystem
Where to upload image
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
s3bucket
YOUR_S3_BUCKET_NAME
bucket name when imageUploadType
is set to s3
config.json
for signin
imgur
environment variables or config.json
for image upload
google drive(google/apiKey
, google/clientID
), dropbox(dropbox/appKey
)
config.json
for export and import
/auth/facebook/callback
twitter
/auth/twitter/callback
github
/auth/github/callback
gitlab
/auth/gitlab/callback
mattermost
/auth/mattermost/callback
dropbox
/auth/dropbox/callback
google
/auth/google/callback
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
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/
License under MIT.