Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Which Wiki text syntax or Markdown to use? [closed]

Working on my personal knowledge base... I want to format my documents, even on local hard disk in wiki syntax. Sometimes I would upload them to a (corporate) wiki, sometimes I would download them from there. Planned are some tools to support this flow and searching my knowledge base (documents) for later. Obviously I want the markdown to be compatible with most, minimising conversion work.

So my question is similar to this related question, but

  • What wiki text version or Markdown (dialect) should I use when I start something new? (i.e. documentation project and kind of wiki).
  • What are the most wiedely used/recognized ones?
  • And where is tool support (editors and or libraries) best? Concerned prog. languages are Java, Ruby, Scala.
like image 995
Peter Kofler Avatar asked Jan 11 '11 09:01

Peter Kofler


People also ask

Does wiki use Markdown?

Wiki. js is an open source wiki application that provides excellent Markdown support.

What is Markdown syntax used for?

Markdown is a plain text formatting syntax aimed at making writing for the internet easier. The philosophy behind Markdown is that plain text documents should be readable without tags mussing everything up, but there should still be ways to add text modifiers like lists, bold, italics, etc.

How do you format a wiki page?

When you go into the editing view of a wiki page, on the right hand side you will see a plus sign. Clicking on it will provide a short list of formatting codes as a help. You can edit this and custom design it for your worksite.

What markup does MediaWiki use?

The MediaWiki markup language (commonly referred to within the MediaWiki community as wikitext, though this usage is ambiguous within the larger wiki community) uses sometimes paired non-textual ASCII characters to indicate to the parser how the editor wishes an item or section of text to be displayed.


2 Answers

Wikipedia says that there is no commonly accepted standard wikitext language.

Creole is one effort for a "common wiki markup language to be used across different Wikis". There is a version 1.0 of the specification and several wikis and wiki engines implement it. MediaWiki does not implement it.

Markdown has a large number of implementations and seems to be used quite a lot.

As there is no agreed standard, the language might be selected depending on features and available implementations depending on the use case.

like image 77
Peter Kofler Avatar answered Oct 21 '22 09:10

Peter Kofler


(1) While there are a lot of wiki markups I suggest to stick to well defined markup language.

There are only 3 plain text markup with well defined specs:

  • CommonMark attempt to define strong syntax and standardize common extensions of popular MarkDown. All love it. Very HTML oriented.
  • reStructuredText is consistent framework for markup and well established project (started from 2001!!). If you need extensibility built into core specs, inline foreign markups, generate HTML/PDF/docbook/etc it is your choice. Several books and many software project was documented via reStructuredText. Check https://readthedocs.org/ With Sphinx publishing software you ever can build HTML with off-line JS search!!
  • AsciiDoc is competitive to reStructuredText but lack of build-in extensibility. It is very DocBook oriented. Several books was written in AsciiDoc.

Textile markup didn't gain well defined specs and has weak community around. I recommend consider above 3 options instead.

(2) You definitely should stick to plain text files.

Support software for all above formats able to produce high quality output for printing and on-line publishing.

I stick to RST because I need extendibility and ability to inline foreign markup (math with LaTeX, graph with graphviz/dot, plotting with imagemagic, etc)

I search over personal tips inside Emacs editor or inside bash/grep. For advertising purpose I publish my tips online, for example: http://tips.defun.work/

like image 23
gavenkoa Avatar answered Oct 21 '22 08:10

gavenkoa