showdoc Documentation

File: README.md Copy Chapter

ShowDoc

[Click here for the Chinese tutorial](https://www.showdoc.com.cn/help) Copy Chapter

What is ShowDoc? Copy Section

When you take over a module or project that was developed by someone else, reading code without any notes or comments can be painful.

Where is the documentation?! Show me the doc!

Programmers often expect others to write technical documentation, but rarely want to write it themselves. Writing good technical documentation takes a lot of time and effort, and involves a great deal of non-technical work, such as deciding on the format and layout, or figuring out which catalog a new Word document should be filed under.

In most teams, Word documents are maintained separately by different people.

How do you get the latest version of a document? Here is a common approach:

You ask around for it. If you're lucky, someone will send you a copy over IM or email. This works, but it is far from the most efficient way.

So, what is the most efficient way? ShowDoc!

ShowDoc is a tool designed for IT teams to share documents online. It improves communication efficiency among team members.

What can it be used for? Copy Section

• API Document ([Demo](https://www.showdoc.com.cn/demo-en))

  With the growth of mobile Internet, BaaS (Backend as a Service) has become increasingly popular. The server-side (backend) provides APIs, and apps or web frontends can conveniently consume data through them. With ShowDoc, you can create elegant API documents quickly and easily.

• Data Dictionary ([Demo](https://www.showdoc.com.cn/demo-en))

  A well-structured data dictionary can clearly present your database schema and define the meaning of every field.

• Explanation Document ([Demo](https://www.showdoc.com.cn/help-en))

  You can use ShowDoc to write tool instructions or technical specification documents for your team to reference.

What features does it have? Copy Section

• Sharing and Exporting

  Responsive web design lets your team read project documents on computers and mobile devices. You can also export a project as an offline Word document.

• Permission Management

  • Public and Private Projects

    Projects on ShowDoc fall into two categories: public and private. Public projects can be viewed by anyone; private projects require login. The password is set by the project owner.

  • Project Transfer

    The project owner can freely transfer a project to someone else.

  • Project Members

    You can easily add or remove project members. Members can edit documents, but only the owner can transfer or delete a project.

• Editing Features

  • Markdown Support

    ShowDoc uses a Markdown editor that is excellent for both writing and reading. If you are new to Markdown, search for "Markdown tutorial" to get started.

  • Template Insertion

    On the editing page, a single click on the button at the top of the editor inserts an API interface template or a data dictionary template. After inserting a template, you only need to fill in the data, which saves a lot of editing work.

  • Version History

    ShowDoc keeps a version history for every page, so you can easily restore a previous version.

Deploy it on your own server Copy Section

• ShowDoc Deployment

  Please refer to: AutoInstall.md

• Development & Contribution

  Please refer to: Development&Contribution.md

Copyright Copy Section

ShowDoc is released under the Apache 2.0 Open Source License and is free to use.

In addition to the Apache 2.0 license, ShowDoc carries an extra copyright notice:

• ShowDoc official and the author star7th hold the copyright and corresponding rights to the program.
• Provided that the copyright information and links on the program UI are retained, the program may be used for free or further development.
• If you need to change the copyright information or links, you must obtain the official consent and authorization.

File: documentation/zh-CN/README.md Copy Chapter

ShowDoc 是什么 Copy Chapter

• 每当接手一个由他人开发好的模块或者项目，看着那些没有写注释的代码，我们都无比抓狂。文档呢？！文档呢？！Show me the doc ！！

• 程序员都很希望别人能写技术文档，而自己却很不愿意写文档。因为写文档需要花大量时间去处理格式排版，还要想着新建的 Word 文档该放在哪个目录等各种非技术细节。

• Word 文档零零散散地放在团队不同成员手里，需要文档的人基本靠吼，吼一声然后通过 QQ 或者邮箱接收对方丢过来的文档。这种沟通方式当然可以，只是效率不高。

• ShowDoc 就是一个非常适合 IT 团队的在线文档分享工具，它可以提升团队之间沟通的效率。

它可以用来做什么 Copy Chapter

• API 文档（[查看 Demo](http://www.showdoc.cc/2)）

  • 随着移动互联网的发展，BaaS（后端即服务）越来越流行。服务端提供 API，APP 端或者网页前端便可方便地调用数据。用 ShowDoc 可以非常方便快速地编写出美观的 API 文档。

• 数据字典（[查看 Demo](http://www.showdoc.cc/1)）

  • 一份好的数据字典可以很方便地向别人说明你的数据库结构，如各个字段的释义等。

• 说明文档（[查看 Demo](http://www.showdoc.cc/3)）

  • 你完全可以使用 ShowDoc 来编写一些工具的说明书，也可以编写一些技术规范说明文档以供团队查阅。

它都有些什么功能 Copy Chapter

• 分享与导出

  • 响应式网页设计，可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成 Word 文件，以便离线浏览。

• 权限管理

  • 公开项目与私密项目

    • ShowDoc 上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问，而私密项目则需要输入密码验证访问。密码由项目创建者设置。

  • 项目转让

    • 项目创建者可以自由地把项目转让给网站的其他用户。

  • 项目成员

    • 你可以很方便地为 ShowDoc 的项目添加、删除项目成员。项目成员可以对项目进行编辑，但不可转让或删除项目（只有项目创建者才有权限）。

  • 团队管理

    • 利用 ShowDoc 的团队功能，你可以更好地进行团队协作。

• 编辑功能

  • Markdown 编辑

    • ShowDoc 采用 Markdown 编辑器，无论是编辑还是阅读体验都极佳。如果你不了解 Markdown，请在搜索引擎搜索"认识与入门 Markdown"。

  • 模板插入

    • 在 ShowDoc 的编辑页面，点击编辑器上方的按钮可方便地插入 API 接口模板和数据字典模板。插入模板后，剩下的就是改动数据了，省去了很多编辑的力气。

  • 历史版本

    • ShowDoc 为页面提供历史版本功能，你可以方便地把页面恢复到之前的版本。

使用在线的 ShowDoc Copy Chapter

• 如果你没有自己的服务器，但又想使用 ShowDoc 作为文档分享工具，你可以使用在线的 ShowDoc：http://www.showdoc.cc
• 在线 ShowDoc 作为在线服务会长期维护，请放心托管数据。

部署到自己的服务器 Copy Chapter

• ShowDoc 部署手册请参考：https://www.showdoc.cc/help?page_id=13732

• 开源地址：https://github.com/star7th/showdoc。若觉得 ShowDoc 好用，不妨点个 star。良好的关注度和参与度有助于开源项目的长远发展。

• 二次开发指引：https://www.showdoc.cc/help?page_id=1385576954326448

ShowDoc 交流群 Copy Chapter

• ShowDoc 使用交流 QQ 群
  • 交流群①：564671853（已满）
  • 交流群②：174709989（已满）
  • 交流群③：667194478

File: documentation/en/AutoInstall.md Copy Chapter

Foreword Copy Section

The automatic script uses Docker to install the runtime environment for Linux servers. If your server does't have a Docker service, the script will try to install it. The process of installing Docker maybe a bit slow. If you have already installed Docker, the script will omit some of the steps to speed up the ShowDoc installation.

When the script fails to install Docker, you should manually install Docker before executing the script. If you still have problem in installing Docker, you can (un/re-)install and debug it step by step according to this tutorial: ByDocker.md

If the server does't support Docker, you can only run ShowDoc by manually installing the PHP environment: DeployManual.md

Instructions Copy Section

# Download the script and run
curl -fL https://www.showdoc.cc/script/showdoc | bash

# Default is the Chinese version. If you want to install the English version, please add the en parameter
curl -fL https://www.showdoc.cc/script/showdoc | bash -s en

Post-installation instructions Copy Section

Once installed, the ShowDoc data will be stored in the /showdoc_data/html directory.

You can open ShowDoc by opening http://your-domain.com:4999 (replace your-domain.com with your server domain name or IP-address).

The default admin account is: showdoc.
The default admin password is: 123456.

After logging in, you can see the management background entry in the upper right. It is recommended to change the password.

For issues or suggestions on ShowDoc, please go to https://github.com/star7th/showdoc for an issue.

Development & Contribution Copy Section

Please refer to: Development&Contribution.md

Upgrade from manual mode to automatic script mode Copy Section

If you have previously installed ShowDoc manually, consider upgrading to this automatic scripting method. After upgrading to the script mode, you can use the automation features of the script, such as upgrading to the latest version, restart, uninstall, etc.

Upgrade method:

1. First refer to the previous section (Post-installation instructions), then install ShowDoc on the server

2. The original ShowDoc directory Sqlite/showdoc.db.php override /showdoc_data/html/Sqlite/showdoc.db.php, Public/Uploads override /showdoc_data/html/Public/Uploads

3. Execute the command

chmod 777 -R /showdoc_data/html
curl -fL https://www.showdoc.cc/script/showdoc | bash -s update

Other commands Copy Section

# Attach the script to other commands, so you can use it when managing ShowDoc.
# Stop ShowDoc
curl -fL https://www.showdoc.cc/script/showdoc | bash -s stop

# Restart ShowDoc
curl -fL https://www.showdoc.cc/script/showdoc | bash -s restart

# Update ShowDoc to the latest version
curl -fL https://www.showdoc.cc/script/showdoc | bash -s update

# Uninstall ShowDoc
curl -fL https://www.showdoc.cc/script/showdoc | bash -s uninstall

File: documentation/en/ByComposer.md Copy Chapter

Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.https://getcomposer.org/
You can install ShowDoc by Composer automatically.

• New installation

Change to web directory（e.g：/var/www/html/）and execute:

composer create-project  showdoc/showdoc

There will be a folder name "showdoc".Open your browser and visit
http://your-domain.com/showdoc/install/ (change to your servser's address) to initialize ShowDoc.

• Upgrade

Stop apache or nginx , and move showdoc folder to bakup

mv showdoc  showdoc_backup

Then flollow the "New installation" guide to install ShowDoc .After that ,move db file and pictures from old folder to new folder.

rm showdoc/Sqlite/showdoc.db.php
cp showdoc_backup/Sqlite/showdoc.db.php  showdoc/Sqlite/showdoc.db.php
rm -r showdoc/Public/Uploads/
cp -r showdoc_backup/Public/Uploads/ showdoc/Public/

Open your browser and visit
http://your-domain.com/showdoc/index.php?s=/home/update/db (change to your servser's address) to update db.

File: documentation/en/ByDocker.md Copy Chapter

Basic installation Copy Chapter

Make sure your environment has Docker installed before installation. The Docker installation tutorial is more online, you can search for it. Here is a highlight of ShowDoc.

# The original official image installation command (Chinese mainland users do not recommend direct use of the original image, you can use the following accelerated image)
docker pull star7th/showdoc

# Chinese Image Installation Command (Remember to execute the Docker tag command after installation to rename)
docker pull registry.docker-cn.com/star7th/showdoc
docker tag registry.docker-cn.com/star7th/showdoc:latest star7th/showdoc:latest

## Follow-up commands need to be executed whether you use official image or accelerated image

# New directory to store ShowDoc data
mkdir -m 777 -p /showdoc_data/html

# Start the ShowDoc container. Don't forget to follow the steps to transfer data after booting.
docker run -d --name showdoc -p 4999:80 -v /showdoc_data/html:/var/www/html/ star7th/showdoc

# Move data When you execute here, pay attention to the error message that the command line interface has permission to prohibit.
# If there is, check the permissions, or security restrictions (for example, selinux may prohibit the Docker process from writing files)
docker exec showdoc cp -fr /showdoc_data/html /var/www/
# permission
chmod 777 -R /showdoc_data

According to the above command, the data of ShowDoc will be stored in the /showdoc_data/html directory.
You can access ShowDoc by opening http://localhost:4999 (localhost can be changed to your server domain name or IP). The default admin account is Username: showdoc Password: 123456 . After logging in, you can see the management background entry in the upper right. It is recommended to change the password after login.
For issues or suggestions on ShowDoc, please go to https://github.com/star7th/showdoc to issue an issue. If you think that ShowDoc is easy to use, please star it.

How to upgrade Copy Chapter

The upgrade here is an upgrade to the above Docker installation. If you used a non-Docker installation (such as PHP installation), please skip this section and go directly to the next section.

## Stop the container
docker stop showdoc

## Download the latest code package
curl -fL https://github.com/star7th/showdoc/archive/master.tar.gz | tar -C /showdoc_data/ -zxv

rm -rf /showdoc_data/html_bak
## Backup. If possible, the html_bak in the command can also be date-suffixed to keep multiple backups of different dates.
mv /showdoc_data/html /showdoc_data/html_bak
mv /showdoc_data/showdoc-master /showdoc_data/html

## Grant permissions
chmod 777 -R /showdoc_data/html

## Start the container
docker start showdoc

## Perform the installation. The Chinese version is installed by default. If you want to install the English version, change the zh in the following parameters to en
curl http://localhost:4999/install/non_interactive.php?lang=en

## Transfer the old database
\cp -f /showdoc_data/html_bak/Sqlite/showdoc.db.php /showdoc_data/html/Sqlite/showdoc.db.php

## Transfer old attachment data
\cp -r -f /showdoc_data/html_bak/Public/Uploads /showdoc_data/html/Public/Uploads

## Perform a database upgrade, see the word "OK" to prove success
curl http://localhost:4999?s=/home/update/db

## If there is an error in the middle, please rename the original /showdoc_data/html_bak file to /showdoc_data/html and restart the container to recover.

How to upgrade non-Docker installation method to Docker installation method Copy Section

First refer to the previous article, use Docker way to install a new ShowDoc, and do data persistence.
Next, assuming that the old ShowDoc you originally installed has been uploaded to the /tmp/showdoc directory of the server, then

## Transfer the old database
\cp -r -f /tmp/showdoc/Sqlite/showdoc.db.php /showdoc_data/html/Sqlite/showdoc.db.php

## Transfer old attachment data
\cp -r -f /tmp/showdoc/Public/Uploads /showdoc_data/html/Public/Uploads

## Perform a database upgrade, see the word "OK" to prove success
curl http://localhost:4999?s=/home/update/db

data backup Copy Section

Just back up the /showdoc_data/html directory. For example, execute the following command to compress and store

zip -r /showdoc_data/showdoc_bak.zip /showdoc_data/html
## where showdoc_bak.zip can be named with a date suffix for multiple backups. You can also use timed tasks to implement scheduled backups.

Other reference commands Copy Section

docker stop showdoc ## stop the container
 docker restart showdoc ## restart the showdoc container
 docker rm showdoc ## delete showdoc container
 docker rmi star7th/showdoc ## delete showdoc image
 docker stop $(docker ps -a -q); docker rm $(docker ps -a -q)  ## Stop and delete all containers. Dangerous orders, do not know how to use.

File: documentation/en/DeployManual.md Copy Chapter

Introduction Copy Section

About ShowDoc , Please refer to /README.md

Environment dependence Copy Section

• Required environment

PHP5.3 or above version ,php-gd,php-pdo

Install and configure Copy Section

• New installation

• Manually download the code from https://github.com/star7th/showdoc/

• Make these writable

Example: sudo chmod -R 777 server/showdoc/install

/install, /Application/Runtime ,/Public/Uploads,/Sqlite,/Sqlite/showdoc.db.php

• Windows sever

  Please entable extension=php_sqlite.dll ，extension=php_pdo_sqlite.dlland php_mbstring.dll in php.ini . Ignore it if you are on Linux.

• Run installation

  http://your-domain.com/install/

• Default Admin

Username : showdoc
Password : 123456

• Upgrade

• Manually download the code from https://github.com/star7th/showdoc/

• Backup your codes via: mv showdoc showdoc_backup

• Dowload new codes and decompression it to a new directory.Copy /Sqlite/* and /Public/Uploads/* from old directory to new directory

• Open http://your-domain.com/index.php?s=/home/update/db in your brown to update database

File: documentation/en/Development&Contribution.md Copy Chapter

Technical stack description

Frontend: Vue + ElementUI

Backend: PHP + Slim 4 + Illuminate/Database

• Architecture: Slim 4 micro-framework + Illuminate/Database ORM
• Core features: PSR-7 HTTP messages, PSR-11 dependency injection, PSR-15 middleware
• PHP requirement: PHP 7.4+ (recommended 8.0+)
• Compatibility: Fully compatible with existing API interfaces and URL formats (including /server/index.php?s=...)

Database: ShowDoc comes with a file database (/Sqlite/showdoc.db.php), no need to manually install the database

Preparation before development

Developing a machine requires first installing the PHP environment and the NodeJS environment.
Download the code and place it in the www directory under the PHP environment

First access in the browser through the address, in order to complete the initial installation of ShowDoc (if it has been installed, ignore it)

Go to ShowDoc's web_src directory on the command line and execute npm install to install the dependencies. (If there is no npm, you must first install the NodeJS environment)

Front-end development

Execute npm run dev to enable the mode, and you can see the effect of the changes in real time by accessing localhost:8080. Please use a proxy to proxy to the PHP server when requesting the backend API.

The npm run build needs to be executed before the final package takes effect. The packaged static files will be in the /web directory.

Mainly related to the directories and files:

Web_src/src/components //page components are basically placed here

Web_src/src/router // page routing. Can target components based on url

Web_src/static // static resource directory

Web_src/static/lang // front-end language pack

Backend development

Mainly related directories and files

Server/app/Api/Controller/ //API controllers directory, all background APIs are placed here

Server/app/Common/Helper/ //Helper classes directory (Security, HttpHelper, FileHelper, etc.)

Server/app/Model/ //Model classes directory (User, Item, Page, etc.)

Server/app/Runtime/Logs/ //Error logs directory, errors will be printed to browser or logged here

Public/Uploads/ //Uploaded images are placed here

Server/app/Api/Lang/ //Backend language pack

other instructions

Please respect the open-source agreement after the second development, retain the copyright-logo and link
If you have developed useful features, you may wish to contribute to the official GitHub code repository for sharing with everyone.

The upgrade of ShowDoc may overwrite your original secondary development. If you want to be compatible, it is best to submit it to the official warehouse to become an official function.

File: documentation/en/README.md Copy Chapter

中文版教程：https://www.showdoc.cc/help Copy Chapter

What is ShowDoc ? Copy Section

Whenever we take over a module or project which has been developed by other people, we always feel crazy watching at those codes without notes. Where is the document?! Where is the document?! Show me the doc !!

A programmer often hopes the others to write technical documents, with the hope of not writing them on his/her own. Because writing a technical document needs a lot of time to handle the format and layout, and the person who writes it has to think of all kinds of non-technical details such as which catalog to put in the newly-established word document

All kinds of the word documents are kept by different persons in a team dispersedly. The person who needs other documents gets the documents by shouting out. He/She gives a shout asking for the documents and then receives them from other people by IMs or the e-mail. This kind of communication is not bad, but the efficiency is not high.

ShowDoc is a tool greatly applicable for an IT team to share documents online. It can promote communication efficiency among members of the team.

What can it be used for? Copy Section

• API Document （ [Demo](https://www.showdoc.cc/demo-en)）

With the development of mobile Internet, BaaS (Backend as a Service) becomes more and more popular. The Server end provides API, and the APP end or Webpage frontend can invoke data conveniently. Using ShowDoc can compile exquisite API documents in a very fast and convenient way.

• Data Dictionary （ [Demo](https://www.showdoc.cc/demo-en)）

A good Data Dictionary can easily exhibit database structure to other people, such as definition of each field and the like.

• Explanation Document （ [Demo](https://www.showdoc.cc/help-en)）

You can absolutely use ShowDoc to compile the explanation documents for some tools, as well as to compile some technical specifications explanation documents for the team to look up.

What functions does it have? Copy Section

• Sharing and Exporting

Responsive webpage design can share the project documents to computer or mobile devices for reading. It can also export the project into word document for browsing offline.

• Permission Management

• Public Project and Private Project

  Projects on ShowDoc are divided into two categories including Public Project and Private Project. Public Project can be visited by any user no matter he/she logs in or not, while inputting password for verification is needed for visiting the Private Project. The password is set by project creator.

• Project Transfer

The project creator can transfer the project to other users of the website freely.

• Project Members

You can easily add or delete project members in the project of ShowDoc. Members of the project can edit the project, but they can not transfer or delete the project (only creator of the project has the permission).

• Edit Function

  • Markdown Edit

  ShowDoc adopts Markdown Editor, and it is excellent both in editing and reading experience. If you know nothing about Markdown, please search “Learning and Introduction of Markdown” on the search engine.

  • Template Insert

  On the editing page of ShowDoc, a click on the button which is on the top of the Editor can easily insert API interface template and data dictionary template. After inserting the template, altering data is the only thing that need to do and it reduces a lot of work in editing.

  • History Version

  ShowDoc provides a function of History Version on the page, and you can easily restore the page to the former version.

Deploy It to Your Own Server Copy Section

• ShowDoc Deploy

  Please refer to: AutoInstall.md

• Development & Contribution

  Please refer to: Development&Contribution.md

Copyright Copy Section

ShowDoc is issued complying with Apache2 Open Source License, and it is for free use.

Copyright © star7th

E-mail: xing7th

All rights reserved.

File: Public/editor.md/lib/codemirror/README.md Copy Chapter

CodeMirror

Funding status:

CodeMirror is a JavaScript component that provides a code editor in
the browser. When a mode is available for the language you are coding
in, it will color your code, and optionally help with indentation.

The project page is http://codemirror.net
The manual is at http://codemirror.net/doc/manual.html
The contributing guidelines are in CONTRIBUTING.md

File: Public/editor.md/README.md Copy Chapter

Editor.md

Editor.md : The open source embeddable online markdown editor (component), based on CodeMirror & jQuery & Marked.

Features Copy Section

• Support Standard Markdown / CommonMark and GFM (GitHub Flavored Markdown);
• Full-featured: Real-time Preview, Image (cross-domain) upload, Preformatted text/Code blocks/Tables insert, Code fold, Search replace, Read only, Themes, Multi-languages, L18n, HTML entities, Code syntax highlighting...;
• Markdown Extras : Support ToC (Table of Contents), Emoji, Task lists, @Links...;
• Compatible with all major browsers (IE8+), compatible Zepto.js and iPad;
• Support decode & fliter of the HTML tags & attributes;
• Support TeX (LaTeX expressions, Based on KaTeX), Flowchart and Sequence Diagram of Markdown extended syntax;
• Support AMD/CMD (Require.js & Sea.js) Module Loader, and Custom/define editor plugins;

README & Examples (English)

Editor.md 是一款开源的、可嵌入的 Markdown 在线编辑器（组件），基于 CodeMirror、jQuery 和 Marked 构建。

主要特性

• 支持通用 Markdown / CommonMark 和 GFM (GitHub Flavored Markdown) 风格的语法，也可变身为代码编辑器；
• 支持实时预览、图片（跨域）上传、预格式文本/代码/表格插入、代码折叠、跳转到行、搜索替换、只读模式、自定义样式主题和多语言语法高亮等功能；
• 支持 ToC（Table of Contents）、Emoji表情、Task lists、@链接等 Markdown 扩展语法；
• 支持 TeX 科学公式（基于 KaTeX）、流程图 Flowchart 和 时序图 Sequence Diagram;
• 支持识别和解析 HTML 标签，并且支持自定义过滤标签及属性解析，具有可靠的安全性和几乎无限的扩展性；
• 支持 AMD / CMD 模块化加载（支持 Require.js & Sea.js），并且支持自定义扩展插件；
• 兼容主流的浏览器（IE8+）和 Zepto.js，且支持 iPad 等平板设备；

Examples

https://pandao.github.io/editor.md/examples/index.html

Download & install

Github download

Bower install :

bower install editor.md

Usages

HTML：

<link rel="stylesheet" href="editormd.min.css" />

    <textarea style="display:none;">### Hello Editor.md !</textarea>

Tip: Editor.md can auto append <textarea> tag;

javascript:

<script src="jquery.min.js"></script>
<script src="editormd.min.js"></script>
<script type="text/javascript">
    $(function() {
        var editor = editormd("editormd", {
            path : "../lib/" // Autoload modules mode, codemirror, marked... dependents libs path
        });

        /*
        // or
        var editor = editormd({
            id   : "editormd",
            path : "../lib/"
        });
        */
    });
</script>

Using modular script loader :

• Using Require.js
• Using Sea.js

Dependents

• CodeMirror
• marked
• jQuery
• FontAwesome
• github-markdown.css
• KaTeX
• prettify.js
• Rephael.js
• flowchart.js
• sequence-diagram.js
• Prefixes.scss

Changes

Change logs

License

The MIT License.

Copyright (c) 2015 Pandao