# HackMD(CodiMD) Integration
# Overview
- HackMD (opens new window) is an excellent tool for concurrent editing on a single Markdown with multiple users.
- CodiMD (opens new window) is an OSS forked from HackMD.
- Integrating HackMD/CodiMD into GROWI allows documents managed under GROWI to simultaneously be edited by multiple people.
# Structure
- By integrating HackMD/CodiMD into GROWI allows HackMD/CodiMD editors to be borrowed and shown in iframe.
- Page data is shared through the medium of window.postMessage (opens new window).
# Create a new HackMD(CodiMD) container with growi-docker-compose
This (opens new window) example will be used.
Set up will follow these instructions README.md (opens new window).
- Prepare
examples/integrate-with-hackmd/docker-compose.override.yml
- Add environment variables to GROWI container
HACKMD_URI
: HackMD server URI which can be accessed from GROWI client browserHACKMD_URI_FOR_SERVER
: HackMD server URI which can be accessed from GROWI server container- System use the same value as
HACKMD_URI
if not set
- System use the same value as
- Add environment variables to CodiMD container
GROWI_URI
: GROWI server URI which can be accessed from client browser
- Start the containers
- From the GROWI Admin page "App settings", set the Site URL
- Input GROWI server URI which can be accessed from client browser
- Another option is to set the
APP_SITE_URL
environment variable
# Integrate with an existing HackMD(CodiMD)
# GROWI Settings
- Set the environment variables below
HACKMD_URI
: HackMD server URI which can be accessed from GROWI client browserHACKMD_URI_FOR_SERVER
: HackMD server URI which can be accessed from GROWI server container- System use the same value as
HACKMD_URI
if not set
- System use the same value as
- Restart
- From the GROWI Admin page "App settings", set the Site URL
- Input GROWI server URI which can be accessed from client browser
- Another option is to set the
APP_SITE_URL
environment variable
# HackMD(CodiMD) Settings
- Set the environment variables below
GROWI_URI
: GROWI server URI which can be accessed from client browser
- Edit ejs to load the GROWI agent:
For HackMD/CodiMD:
Add below to the end of
/codimd/public/views/codimd/head.ejs
<script src="<%= process.env.GROWI_URI %>/_hackmd/load-styles"></script>
Add below to the end of
/codimd/public/views/codimd/foot.ejs
<script src="<%= process.env.GROWI_URI %>/_hackmd/load-agent" defer></script>
For HedgeDoc:
Add below to the end of
/hedgedoc/public/views/hedgedoc/head.ejs
<script src="<%= process.env.GROWI_URI %>/_hackmd/load-styles"></script>
Add below to the end of
/hedgedoc/public/views/hedgedoc/footer.ejs
<script src="<%= process.env.GROWI_URI %>/_hackmd/load-agent" defer></script>
- Restart
# Validation
# GROWI
- When showing an arbitrary editable page, check that the HackMD tab is shown.
# HackMD(CodiMD)
- When showing an arbitrary editable page, check that the log below appears in the browser console.
[GROWI] Loading styles for HackMD is not processed because currently not in iframe [GROWI] Loading agent for HackMD is not processed because currently not in iframe
# Troubleshoot
# HackMD tab doesn't appear in GROWI
- Check whether the correct value is set in
HACKMD_URI
# Error when pressing "Start to edit with HackMD"
# Error: Connecting to a non-HackMD server
- Check whether the correct value is set in
HACKMD_URI_FOR_SERVER
- Check the communication between the GROWI server and HackMD/CodiMD
# GROWI client failed to connect to GROWI agent for HackMD
- Check whether the correct value is set for the GROWI Site URL
- When making changes to existing HackMD/CodiMD, check whether
- content inserted into head.ejs and foot.ejs are correct
- the URL from the src attribute of the script tag inserted into the source code of HackMD/CodiMD can be accessed successfully (can load the CSS and JavaScript).
# Error when pressing "Update", and GROWI session expires ("/login" appears when you move to another page)
- The session cookie names
connect.sid
are conflicting between GROWI and HackMD/CodiMD- Set the environment variable
SESSION_NAME
in GROWI to change the cookie name
- Set the environment variable