EasyDoc

A powerful technical documentation tool that generates completely local HTML pages and websites from markdown files.

created by:

Features

Install

Clone with git from master branch:

# clone via https:
git clone https://github.com/grandgeorg/easydoc.git
# or clone via SSH (if you have a key):
git clone git@github.com:grandgeorg/easydoc.git

Change into easydoc directory and run install:

cd ./easydoc/
npm install

You could now use EasyDoc from this directory, but we recommend, that for your documentations in different paths you use the setup.js from EasyDoc as follows:

# cd to some directory in some project of yours, where you want to setup your documentation with EasyDoc
cd /some/project/docs
# run setup.js from easydoc with node
# e.g. node D:\\srv\\vhost\\easydoc\\index.js
# in powershell you can use the following command:
# node (Get-Item -Path "D:\\srv\vhost\easydoc\index.js").FullName
node /path/where/you/cloned/and/installed/easydoc/setup.js
# edit newly generated config files (.env, nav.js, package.json - author, description, keywords) in /some/project/docs ...
# put some md-files into docs directory
# you can now run
npm run build
# if you also want to use nodemon to watch your file changes first run
npm install
# then you can run
npm run watch

Usage

# watches on file changes and runs build:
npm run watch
# or build one time
npm run build

🗁 easydoc
 ├🗀 .git
 ├🗀 .vscode
 ├🟢 docs
 │ └🗏 index.md 🖤
 ├🗀 lang 🖊️
 ├🗁 manual 📌
 │ ├🗀 assets
 │ ├🗀 img
 │ ├🗏 easydoc.html
 │ ├🗏 easydoc.md
 │ ├🗏 easydoc-reference.html
 │ └🗏 easydoc-reference.md 
 ├🗀 node_modules
 ├🗀 setup 🖊️
 ├🗀 src 🖊️
 ├🗀 templates 🖊️
 ├🔵 www
 │ ├🗀 assets 🖊️
 │ ├🟢 img
 │ ├🗏 index.html 🖤
 │ └🗏 meta.js 🖤
 ├🗏 .env ✏️
 ├🗏 .gitignore
 ├🗏 .hintrc
 ├🗏 index.js 🖊️
 ├🗏 nav.js ✏️
 ├🗏 nodemon.json
 ├🗏 package.json
 ├🗏 package-lock.json
 └🗏 webpack.config.js

╭──────────────────────────═━┈💬┈━═──────────────────────────╮
│  🟢 input directories. Start creating files here.          │
│  🔵 output directory. Html files will be generated here.   │
│  ✏️ configure EasyDoc                                      │
│  🖊️ change EasyDoc                                         │
│  📌 It's me. You are reading these documents right now.    │
│  🖤 Remove these documentation files for a blank start.    │
╰──────────────────────────═━┈💬┈━═──────────────────────────╯

For configuration and further usage refer to the EasyDoc Reference

Workflow

For the most convenient use do the following:

1. Start Visual Studio Code from the easydoc directory.
2. Start the Live Server extension.
3. Run npm run watch.
4. Put the vscode and the browser window side by side.
5. Start creating and editing markdown files in docs directory.
6. Use git if working in a team.

Deployment

You can deploy your generated documentation to a server using

npm run deploy

Make sure to configure the deployment settings in the .env file before running the deploy command.

The deployment process will build your documentation and then upload it to the specified server using the configured method.

SFTP Deployment

For now the only supported deployment method is SFTP. You can configure the SFTP settings in the .env file.

EASYDOC_DEPLOY_TYPE=sftp

# SFTP deployment (runs `npm run build`, then uploads the built site).
EASYDOC_DEPLOY_SFTP_HOST=example.com
EASYDOC_DEPLOY_SFTP_PORT=22
EASYDOC_DEPLOY_SFTP_USERNAME=user
# Use a private key (preferred) OR a password.
EASYDOC_DEPLOY_SFTP_PRIVATE_KEY=/path/to/id_rsa
EASYDOC_DEPLOY_SFTP_PASSPHRASE=
# Use a password auth instead of a private key.
EASYDOC_DEPLOY_SFTP_PASSWORD=
# Remote directory the site is uploaded into.
EASYDOC_DEPLOY_SFTP_REMOTE_PATH=/var/www/vhost/doc.yourdomain.tld/public/some-doc
# Local directory to upload (defaults to the built output: www).
EASYDOC_DEPLOY_SFTP_LOCAL_DIR=www

For more information on deployment, refer to the EasyDoc Reference