DeepWiki

A lightweight wiki system, based on Markdown, coded in PHP.

• Contributor: Yuan Chong
• License: Apache License, Version 2.0
• Live Demo: https://deepwiki.chon.io/

Installation

1. Download the latest release of DeepWiki.
2. Unarchive package.
3. Done.

Quick Start

1. Make a configuration file from the sample.
2. Write down some Markdown files into deepwiki-docs/.
3. Run it in PHP.

Configuration

Main configuration is placed in deepwiki-config/config.json, can be made from the sample file deepwiki-config/config-sample.json:

{
	"site_name"        : "DeepWiki",
	"site_description" : "Markdown Documents Showcase",
	"copyright"        : "Powered by <a href=\"https://github.com/ychongsaytc/deepwiki\" target=\"_blank\">DeepWiki</a>.",
	"theme"            : "default",
	"docs_path"        : "deepwiki-docs-example",
	"assets_path"      : "deepwiki-docs-example/assets",
	"home_route"       : "quick-start",
	"display_chapter"  : false,
	"display_index"    : false,
	"rewrite"          : false,
	"footer_code"      : "",
	"password"         : "",
	"cookie_salt"      : "REPLACE_THIS_WITH_A_RANDOM_STRING"
}

Directory Structure

deepwiki-docs/                   Document files in Markdown, plain text, HTML
             /index.json         A JSON specified all document titles, filenames, slug names and hierarchy
             /assets/            Asset files (e.g. images and attachments)
deepwiki-config/config.json      Main configuration file in JSON
deepwiki-themes/                 DeepWiki themes
               /default/         The default theme of DeepWiki
               /xxx/             A theme named xxx
deepwiki-vendor/                 The necessary components

Writing Documents

All documents must be placed in DeepWiki documents directory (defaults to deepwiki-docs/, can be changed in DeepWiki configuration).

Arrange your documents through file naming

Basic way to arrange your documents, will be overwrite by the definition in DeepWiki configuration (see Define all documents in configuration below).

Full functional naming example

1. Parent Page One [parent-1].md
1.1. Child Page One [child-1].md
1.2. Child Page Two [child-2].md
1.2.1. Grandchild Page One [grandchild-1].md
1.2.2. Grandchild Page Two [grandchild-2].md
1.2.3. Grandchild Page Three [grandchild-3].md
1.3. Child Page Two [child-3].md
2. Parent Page Two [parent-2].md
3. Parent Page Three [parent-3].md

1. Chapter Number: (optional) Using digits or letters ended with a point (.). If not set, the document will act in flat hierarchy.
2. Document Title: (mandatory) The title of document.
3. Document Slug Name: (optional) A string to be the identifier (or short name) of the document, enclosed by a pair of square brackets ([ and ]). Leave this blank to use sanitized document title as slug name.
4. Document File Extension Name: (mandatory) Possible values are: .markdonw, .md, .mdown, .txt, .html, etc.

More examples

Pure titles, without hierarchy

Umentia.md
Ventis.md
Boreas.md
Bracchia.md
Congestaque.md

Using letters as chapter, with hierarchy

A. Crescendo.md
B. Mundum.md
C. Fulgura.md
D. Habendum.md
D.1. Discordia.md
D.2. Instabilis.md
D.3. Erectos.md
D.3.a. Utramque.md
D.3.b. Flamma.md
E. Scythiam.md

Define all documents in configuration

The documents can be defined in configuration file (deepwiki-docs/index.json), including titles, slug names, filenames and hierarchy.

Sample configuration:

{
	"home": {
		"title": "Home",
		"file": "home.md"
	},
	"products": {
		"title": "Products",
		"file": "",
		"children": {
			"category-a": {
				"title": "Category A",
				"file": "product/category-a.md"
			},
			"category-b": {
				"title": "Category B",
				"file": "product/category-b.md"
			}
		}
	},
	"global-site": {
		"title": "Global Site",
		"file": "http://example.com/"
	}
}

Inner page linking and asset files linking

DeepWiki will perform transforms after document content is parsed. There are two transformers:

Examples

Think about the website root URL is http://example.com/path/to/wiki/:

• [Contact Us](#about/contact-us) will be parsed into:

   <a href="/path/to/wiki/about/contact-us">Contact Us</a>

• [Click to view full size](!/full-size-image.jpg) will be parsed into:

   <a href="/path/to/wiki/deepwiki-docs/assets/full-size-image.jpg">Click to view full size</a>

• ![Website Logo](!/logo.png) will be parsed into:

   <img src="/path/to/wiki/deepwiki-docs/assets/logo.png" alt="Website Logo" />

Auto Deployment for Documents

If you are using Git to manage your documents, you can setup an auto deployment tool to deploy files onto DeepWiki.

DeepDeploy is such an Auto Deployment system, deploying Git repository to any server (via FTP/SFTP). It's easy to use:

1. Go to DeepDeploy, sign in and create a project.
2. Add your repository contains document file to the project.
3. Add your DeepWiki server FTP/SFTP information to Server section, with setting Path to Deploy to the DeepWiki document files path (e.g. /deepwiki-docs/src or /home/ubuntu/public_html/deepwiki-docs/src).
4. Save the project and trigger your first auto deployment.

Theme Development

DeepWiki allow you to custom your own template. The files structure is:

deepwiki-themes/xxx/             A theme named xxx
               /xxx/theme.json   Theme configuration in JSON
               /xxx/index.html   Document page template
               /xxx/404.html     Not Found (404 HTTP status) page template
               /xxx/login.html   User Login page template

Sample theme configuration:

{
	"name": "A DeepWiki Theme",
	"assets": {
		"css": [
			"css/web.css"
		],
		"js": [
			"js/web.js"
		]
	}
}

Functional elements in template files:

URL Rewrite

For Apache HTTP Server

Place the code in the /.htaccess file.

# prevent directory listing
Options -Indexes

# custom error documents
ErrorDocument 404 index.php\?p=_404
ErrorDocument 403 index.php\?p=_403

<IfModule mod_rewrite.c>
RewriteEngine on

# change / to your DeepWiki relative directory path, eg. /path/to/wiki/
RewriteBase /

# prevent illegal request
RewriteRule ^deepwiki-config/(.*)$ index.php\?p=_403 [L]
RewriteRule ^deepwiki-docs/((?!.*?assets).*)$ index.php\?p=_403 [L]
RewriteRule ^deepwiki-docs-example/((?!.*?assets).*)$ index.php\?p=_403 [L]

# rewrite non-exist path to index.php
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php\?p=$1 [QSA,L]

</IfModule>

For Nginx

Place the code inside the http { ... } node in Nginx configuration file.

server {

	# bind to http://example.com on port 80
	listen 80;
	server_name example.com;

	# change this to your DeepWiki root path
	root /var/www/deepwiki;

	# custom error documents
	error_page 404 =404 /index.php\?p=_404;
	error_page 403 =403 /index.php\?p=_403;

	# prevent illegal request
	location ~ /(deepwiki-config\/) {
		deny all;
	}
	location ~ /((deepwiki-docs|deepwiki-docs-example)\/((?!.*?assets).*)) {
		deny all;
	}

	# rewrite non-exist path to index.php, or return HTTP 404 Not Found
	location / {
		try_files $uri $uri/ /index.php?p=$uri&$args;
	}

	# example of passing request to FastCGI
	fastcgi_param PHP_VALUE "open_basedir=$document_root:/tmp/";
	location ~ \.php$ {
		fastcgi_pass unix:/tmp/fastcgi-php.socket;
		fastcgi_index index.php;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
		include fastcgi_params;
	}

	# prevent from requesting Apache HTTP Server configuration files
	location ~ /\.ht {
		deny all;
	}

}

Change Log

1.2.0 2017-01-05

• FIXED: #3 Nicer sanitizing
• TWEAK: Move JS to the end of the <body> tag

1.2.0 (beta1) 2016-04-08

• NEW: Moved docs index tree configuration to docs root directory
• TWEAK: Add http status for 403 and 404
• TWEAK: Updated vendor components
• FIXED: Sorting for chapter more than 2-figure string

1.1.1 (beta3) 2015-08-11

• TWEAK: Updated vendor components
• TWEAK: Optimized URL

1.1.1 (beta2) 2014-12-08

• NEW: Supported to generate content outline index
• NEW: Automatically add anchor to content headings

1.1.1 (beta1) 2014-12-07

• NEW: Supported Responsive CSS

1.1.0 (beta2) 2014-12-06

• FIXED: Redirection bug for root visits

1.1.0 (beta1) 2014-12-06

• NEW: Allowed to define all document titles, filenames and slug names in configuration instead of using file naming
• NEW: Supported inner page linking and asset files linking in document content
• NEW: Implemented Prism to highlight code blocks in DeepWiki Default Theme
• NEW: Minified all assets files in DeepWiki Default Theme
• NEW: Included necessary components in DeepWiki Git repository for easier installation

1.0.0 (beta1) 2014-11-14

• NEW: Born

Credits

Thanks to

• Parsedown by Emanuil Rusev (implemented to DeepWiki)
• Bootstrap (implemented to DeepWiki Default Theme)
• jQuery (implemented to DeepWiki Default Theme)
• Prism (implemented to DeepWiki Default Theme)
• GitHub Markdown CSS (implemented to DeepWiki Default Theme)