Project Documentation

building beautiful documentation, open-source knowledge base, documentation generators, internal wiki, technical documentation, software documentation

I want to have documents in my “Treasury” file structure, but at the same time I want to display them in a nice way to other colleagues. The problem arose from the unfortunate fact that Google Drive doesn’t have any kind of Markdown preview. And that was the reason why I needed to find a better solution.

There are a lot of possible approaches out there, and almost every one of them has a major flaw in it.

Old School: Store Documents in Cloud

Store documents in Google Drive and view them with MDWiki

This is no longer a viable option as Google has announced that they will stop hosting files after 31. August 2016. This means that it will no longer be possible to access files using the www.googledrive.com/host/[doc_id] URL.

News source article

A few more tricks: How to create direct download links for files in Google Drive

Note: I can’t seem to get the full text search to work on the .md files in Google Drive - it just doesn’t work.

Host documents on Seafile natively

Hosting documents natively on a Seafile server allows for the use of its built-in, visually appealing markdown viewer.

However, to ensure that changes made to the documents are recognized, we must use hard-links from my Google Drive to Seafile. Soft directory links are not viable as Seafile file watcher will not pickup changes on files.

While hosting all documents on Seafile may seem like a good idea, it’s important to note that the search functionality is not stellar; in fact, it is non-existent. Also note that full-text search is available only in the Pro version, which is free for up to 3 users.

Storing documents in Dropbox

Dropbox has some rudimentary preview support for Markdown, plus web hosting is possible so we can also use much more advanced MDWiki markdown preview.

Problem is that it doesn’t support full-text search in their free accounts.

I won’t migrate my notes to Dropbox, but I can use hardlinks to Dropbox, if I ever want to ditch Seafile thing setup in the same way.

Temporary but simple solution

For some past projects and customer documentation, I used to create a separate non-encrypted library inside Seafile, and I have set that synced folder on my computer is at the same location as Google Drive folder. Therefore, I have avoided creating hard links or anything similar, and I don’t need to use MDWiki as Seafile has beautiful Markdown preview.

New Wave: The Power of Markdown and SaaS

Advanced Solutions That Outshine Their Predecessors

This is a continuation of the original text, as I have once again found myself delving into this topic in October 2020. I consistently return to this problem, yet I still haven’t found the ideal and free solution.

I feel as though I have finally stumbled upon some solutions that somewhat satisfy my needs. My main desire is to be able to share a hidden document and write documentation without relying on GitHub. If only Asana had a proper Documents/Wiki module, I wouldn’t have to deal with this at all.

I’ll rank the solutions according to my personal quality assessment, UI design and aesthetics, and usability for my intended purposes.

To conclude, I’ll say that I haven’t found the perfect solution yet unless I decide to self-host, in which case I have at least two ideal options: Boost Note and Outline, but it’s hard to choose which one is better.

GitBook

GitBook has the tagline “Where technical teams document,” which speaks for itself. It looks stunning, and I know that it’s widely used on the internet. GitBook is a modern documentation platform that works in collaboration with GitHub. If I were genuinely open-source developer, which I’m not, I would have get everything for free, including a custom domain. Anyway, even as it stands now, there are some restrictions but they’re not terrible.

I believe that it would be perfect if I paid for it. As it is, it’s still excellent, but I’m unsure about what I’ll encounter later. Nonetheless, the UI is beautiful, the interface is excellent, and everything is top-notch. Moreover, I don’t think it’s open-source anymore, so I can’t self-host it, that’s for sure.

GitBook stopped being fully open-source in September 2020 when they introduced changes to their licensing model.

Wiki.js

Wiki.js is a highly professional product designed specifically for this purpose, with the slogan “Make documentation a joy to write”. It looks really slick and since it is open-source, it is also self-hosted. There is, of course, a guide on how to sel-host using Docker.

I believe this is an exceptional product, on par with Outline and perhaps even better, although they both need to be tried out.

Boost Note

Boost Note is a document-driven project management tool. As odd as it may sound, it means that it competes with Asana and the like, but with a focus on documentation. I can relate to that, and I like the idea. When I tested it earlier, I noted that it works well with images but doesn’t support a custom domain for free. It appears to work very well now with privileges, users and teams.

I knew there had to be a catch! They don’t have a free plan at all, only a trial. And once the 14-day trial is over, what happens? You will not be able to add and edit documents, but you’ll still be able to read the existing documents. It’s a complete lockdown until you pay.

That concludes my analysis of this excellent tool, until I decide to self-host it, in which case I’ll need the repo ready: BoostIO/BoostNote-App

GitHub

GitHub is a decent option. Markdown looks great. The only issue is with document sharing, as documents are “too visible,” even when using “secret” Gists. But when you use them, file management becomes a pain because it is really hard to work “in one file.”

Overall, GitHub is not a bad solution, but it is not ideal either. However, with some build process, I might be able to create something ideal.

Outline

Outline looks really slick. After some technical research, it was confirmed that it is complete and without any major shortcomings, possible to self-host. There is no free cloud offering, only a trial period, but that’s okay. When I compare the free self-hosted option with paid packages, nothing significant is missing. The downsides are there if I don’t want to self-host and that’s precisely what I often want.

HedgeDoc

HedgeDoc is my old acquaintance who has always been “almost” ideal, but never quite made it.

This is the former CodiMD or HackMD, it is really incredible how long they “wandered” around those sharing and merging and everything else. Read and marvel: History: HedgeDoc is the fork of CodiMD, which is the counterpart to HackMD. Confused?. To summarize the current state, here’s how things stand and this is what’s important now:

• HedgeDoc is completely open-source and self-hosted, but there is no public free plan, and there are no teams when you self-host, which is not tragic. The situation is similar to Outline.
• HackMD is free SaaS remains always free, but there are no teams, and there is a limit of 3 invitees, which are “like” team members.
• HackMD EE as Enterprise Edition is an enhanced version of the regular HackMD, as SaaS with teams. There is a demo, but don’t get carried away as it resets weekly. They guarantee that the regular HackMD will always exist as free.
• CodiMD became HedgeDoc, and this is an archived repo, and let’s say it doesn’t exist anymore.

Previous observations related to HackMD that I used, are that the search is really bad, but that was not a problem for technical documentation and working with a team, while for personal use as a second-brain it would be a big problem. Also, you can’t set a custom domain in the free version, which is expected.

Type.md

Type.md allows you to manage your documents using Google Drive and Markdown and offers a generous free plan with almost no limitations. The website even mentions a use case such as “internal wiki” or “knowledge management tool”, which is exactly what I intend to use it for. However, the biggest issue I see is the focus on the Japanese language, which is apparent everywhere on the site. Additionally, it seems that they have not yet defined a pricing strategy, which makes me afraid of future changes. Also, it appears that everyone must log in with their Google account to view the documentation, which is not suitable for me.

Pepperminty-Wiki

Pepperminty Wiki is a complete Wiki project in PHP, contained in a single file. As an idea, it is excellent, and according to the specifications, it also supports Markdown and is quite modern, but the UI really looks terrible. The repo is here sbrl/Pepperminty-Wiki.

SlimWiki

SlimWiki has the slogan “Beautiful Wikis for Teams” and as such, it should be ideal for me. The Markdown document pasting feature works great, although it loses the links. The opposite process, export, loses almost all formatting. However, the end result looks quite nice, even though the user interface is average. Also, it supports custom domain for free.

Outdated: I’ve found a “catch”! The free version is limited to 3 team members, but the bigger problem is that you can only do Markdown Export or, more dreadfully, have “Public Pages” after you pay. This renders it unusable since I have a limit of 3 users, meaning only 3 people can participate in just viewing documentation. Just forget about it.

Update 2024: It seems that some changes have been made, as the export now works, and it is allowed for 5 users instead of 3. I am currently unable to insert or import my markdown, as the export is no longer in MD format but as generated HTML.

Crisp Docs

crisp-oss/chappe is from the arsenal of modern tools. It’s a tool like Hugo or any other SSG, but Chappe is made specifically for Developer Docs. Like the others, it produces static assets and has no runtime, just lightweight static files. It comes with a built-in search engine and whole content is written in Markdown. It’s not bad, but I don’t see the real advantage over any other SSG with a suitable theme.

Matterwiki

Matterwiki looked interesting with its slogan “beautiful wiki for teams”, but development is slowly fading away, so forget about it.

Notaku

Notaku, while not open-source, represents an innovative idea that is excellent for building documentation websites with Notion. There is a free plan available that offers a maximum of 20 Notion pages per site, hosted on the notaku-branded subdomain.

Blot

Blot converts files you put inside a Dropbox or Google Drive folder, into posts on your website, ali nažalost nije besplatan. Sa druge strane, meni je vrlo interesantan, jer jeste open-source na repo davidmerfield/Blot a koristi node.js, pa možeš sasvim normalno da ga koristiš.

Lark

Lark is a workplace platform developed by ByteDance, the Chinese tech giant behind TikTok. It offers a suite of tools including video conferencing, chat, document collaboration, project and team management, and file sharing, all integrated into a single platform.

Originally modeled after Slack, Lark offers generous messaging limits with unlimited message history storage. It also has an excellent email module that, like Yandex Email, supports custom domains for free. What’s even more impressive is that it offers all these features completely free for up to 50 users, not just 5 or 10.

One of the drawbacks is that, for instance, the email client does not support Firefox, only Chrome.

Markdown support in the Wiki module is essential for me, and while it exists, it’s not “native”, as you’ll read in my analysis below.

Modules offered by Lark:

• Messenger module, similar to Slack
• Lark Drive, similar to Google Drive, with 100GB of storage in the free plan
• Docs, similar to Google Docs
• Sheets, a basic spreadsheet similar to Google Sheets
• Meetings module, similar to Zoom
• Calendar module, similar to Google Calendar
• Email module, which you can link to a Gmail account and work seamlessly from within Lark
• Wiki module, which is great for knowledge management and allows for easy importing from Confluence and other platforms

Lark offers some innovative modules that are not commonly found in other applications, especially not for free, including:

• Mindnotes, for creating mind-map documents
• Approval module, which enables you to submit and process approvals with the ability to design your own approval process flow
• Minutes module, which is linked to the Meetings, automatically transcribing video meetings into transcripts
• Bitable, a next-generation database platform similar to Notion or Airtable
• OKR module, for defining and managing goals at all levels, both individual and team-based
• Lingo module, which is like a Wikipedia that allows all members to contribute, typically for company acronyms and jargon

App Directory aka “The Open Platform” already has a solid collection of mostly free official add-ons. Most add-ons work well on the desktop application, but some basic functionalities, such as Docs, insist on redirecting you to the browser.

Here are some of the useful modules:

• Lark Survey as a replacement for SurveyHero
• Attendance module not only offers a plethora of standard options but also provides several amazing features for employees to clock in and out. These options include using the mobile app, GPS, Wi-Fi MAC address, and even taking photos. Moreover, this module also includes a “Buzz” feature that sends an urgent alert to a specific person, notifying them that a message requires their immediate attention.
• Lark Flow, which is like IFTTT or Zapier. While it doesn’t have nearly as many integrations, it works for all Lark applications and modules and includes Webhooks and some basic external apps such as Typeform.

Lark also offers expected and nearly default connectors, including:

• Zoom Connector
• Trello Connector, which seems to be able to search Trello cards
• Asana Connector
• GitHub Assistant

The only downside is that it focuses solely on the Asian market, with most language options limited to English, Chinese, and Japanese, while others are neglected. Moreover, a notable inconvenience is that whenever the app prompts for location, it must be entered in Chinese. Therefore, you must first translate the city name on Google Translate and then copy-paste it into the field in Lark.

Markdown support

Pasting Markdown into Docs does not work perfectly, far from it, as it does not transfer links correctly. In fact, inputting a Markdown document is similar to Notion in that it works if you type it out directly, but not if you paste it.

The only way to properly insert Markdown is through the “upload file” option. However, in this case, it behaves more like Dropbox because you cannot edit the document, but you can still download it in its original format. Nevertheless, this is a fairly decent solution, except that users cannot edit MD files directly in the Wiki.

Other interesting features

It is worth noting that there is an interesting option to import a complete zip file from Confluence.

Fortunately, Docs is outstanding, and sharing, for example, is logical and well done. It supports the integration of some truly great blocks, such as Quick Pools, a nice Flowchart editor, embedded tables, callouts with changing icons, equations in LaTeX format, website cards, various map and YouTube embeds, TikTok, Figma, and CodePen (nice!).

I would like to point out that if you input a document directly into Docs, exporting it to Markdown is not available, which is a significant drawback.

Revisiting an old idea

I am returning to familiar territory that I once frequented. Specifically, I have a new-old idea to incorporate something like MdWiki client-only within WP, which would use only JavaScript to render Markdown and effectively serve as sophisticated technical documentation within a WordPress installation.

I essentially see no compelling reason for PHP to be required, but if I am unable to avoid it, then so be it.

Search functionality would be desirable but not obligatory, since I am unsure of how to implement it without a PHP build process or some specialized PHP handling for creating a search index.

Engines That Require Build Process at Backend

PHP is required

Daux.io is an documentation generator written in PHP that uses a simple folder structure and Markdown files to create custom documentation. Very actively developed at repo dauxio/daux.io. In the past, there was annoyance that we must use underscores instead of spaces in filenames.

BookStack is amazing open-source platform to create documentation content built with PHP, MySQL and Laravel, with repo at BookStackApp/BookStack. It’s very feature-complete and also a markdown editor is provided and includes a live-preview as you write your documentation.

Sculpin is PHP Static Site Generator

JigSaw is simple SSG with Laravel’s Blade

Couscous turns Markdown documentation into beautiful websites, developed at PHP repo CouscousPHP/Couscous

devaneando/Wikitten was small PHP wiki, but abandoned now.

Node.js required za build proces

Retype is an actively developed Node.js generator available at retypeapp/retype that should be used to generate, publish, and share documentation.

Docusaurus is latest addition and open-sourced in december of 2017 by Facebook for building easy to maintain documentation websites. Repo is at facebook/docusaurus. That’s exactly for my use case. Built with React, needs Node.js on server for the build and supports Algolia documentation search. A great example of Docusaurus documentation can be found on the website infinum/eightshift-docs of the Croatian company Infinum.

Markdoc is node.js based and Markdown-based toolchain for creating custom documentation sites, developed at repo markdoc/markdoc is made by Stripe, and used at amazing Stripe Documentation

Docpress na repo docpress/docpress je slična ideja iako on traži node.js u build procesu, tako da je suštinski različit

chutsu/ditto was node.js lightweight Markdown Documentation System, abandoned long ago.

Build Process Step in Python, Rust, Go or Java

MkDocs is a fantastic Python-based tool for creating project documentation using Markdown. The Material for MkDocs theme on the squidfunk/mkdocs-material repository is truly a beautiful choice.

Read the Docs je Python based, potpuni open-source na repo readthedocs/readthedocs.org

Sphinx is granddaddy Python project that makes it easy to create intelligent and beautiful documentation.

Nikola is active developed in Python at getnikola/nikola

Gollum Wiki je git-based Wiki pisan u Ruby i bio je oficijelni Wiki engine za GitHub Pages, ali sada se to dosta razlikuje.

mdBook is Rust based command-line tool that allows you to create a book from markdown files, similar to GitBook. The output looks great, and the project is actively developed on rust-lang/mdBook .

SkyDocs is Java based lightweight static documentation builder with MarkDown, sa poslednjim commitovima u 2020 na repo Skyost/SkyDocs

gechandesu/owl is Python minimalistic knowledge base web app with last commits in 2021.

jeromegn/DocumentUp is Ruby documentation generator that is long abandoned.

Markdown-based Client-Only Documentation Generator

A library that can be used for this purpose is Showdown.js, a bidirectional Markdown-HTML-Markdown converter written in Javascript developed at showdownjs/showdown.

The same idea has been implemented at oscarmorrison/md-page.

Docsify

Docsify is identical to MDWiki, but is actively developed on the repository docsifyjs/docsify. Check out docsifyjs/awesome-docsify, which is full of beautiful tools and solutions.

For example, this is a beautifully simple tool: Docsify-This, which instantly turns Markdown files into web pages.

jhildenbiddle/docsify-themeable: A delightfully simple theme system for docsify.js. Features multiple themes with rich customization options, an improved desktop and mobile experience, and legacy browser support (IE11+).

Refer to the basic DocsifyJS Tutorial or this one with images How to Write Good Documentation with Docsify for detailed guidance.

MDWiki

The first tool I came across was MDWiki, which is absolutely perfect, except for the fact that it is no longer being developed. A boilerplate folder can be found in this repository exalted/mdwiki-seed. MDWiki can be extended through Gimmicks aka plugins, and here are some interesting ones utensil/mdwiki-gimmicks.

Unfortunately, the project has been abandoned, but there are forks that keep it alive: re-pesk/mdwiki.

Docute

egoist/docute has no build process, and the website is generated on the fly, but unfortunately, it is no longer actively maintained.