I would like to propose a step-by-step migration of fandoc to markdown.  When we first created fandoc 20 years ago there were many competing plain text formats so it was only loosely based on markdown.  But now markdown is definitely the winner, so it would be good to start the process of standardizing on it.

Last year Matthew ported a Java library with full support for Commonmark to Fantom via the new markdown pod.  This pod also supports an extension mechanism.  So this will be the new standard parser for documentation.

Proposed Initial Scope

My initial proposal is to convert only fandoc chapters files from .fandoc to .md.  We will continue to use fandoc for all in-code documentation in .fan files, and also leave the forum posts in fandoc format for now.  For example we would convert all the fandoc chapters of docLang, docDomkit, etc as well as in-pod chapters such as web/pod.fandoc.  With this change, all the documentation files will be formatted nicely on GitHub and more easily edited/previewed using standard tools.

Proposed Syntax

The proposed syntax is the Commonmark specification as our standard markdown grammar with a few extensions:

• disable support for inline HTML
• support for GitHub style tables
• maintain support for link shortcuts using [foo] syntax

Currently we use the following syntax for inline links as covered here:

**APIs:**
- `sys::index`: pod index
- `web::pod-doc`: pod documentation
- `sys::Str`: API for type
- `sys::Str.getRange`: API for slot
- `Int`: API for type (internal to pod)
- `Int.toHex` API for slot (internal to pod)
- [now]`sys::Duration.now` API with anchor text

**Manuals:**
- `docLang::index`: pod index
- `docLang::Closures`: chapter
- `docLang::Closures#syntax`: anchor within chapter
- `Env`: chapter (internal to pod)

- `Env#index`: anchor within chapter (internal to pod)

With a full conversion to markdown the backticks will become inline code and will no longer be a link.  Instead will will allow a specialized link syntax using only square brackets:

// current shortcut link to Str type
This is a link to `sys::Str`!

// proposed shortcut link to Str type
This is a link to [sys::Str]!

// which is essentially a shortcut for this
This is a link here [sys::Str](sys::Str)!

This link syntax allows us to still easily use terse hyperlinks, but much closer to markdown syntax.

Comments and feedback welcome!

Followup to this topic. Everything is ready to be converted. This week we have made two changes to the code:

1. There is a new adm/fandoc2md.fan script that will convert type/slot comments and fandoc chapters into markdown
2. The compilerDoc code has been enhanced to support both fandoc and markdown with full backward compatibility

To keep everything backward compatible, we are going to assume that all pods are using fandoc for their comments unless you opt in to tell compilerDoc that you are using markdown for the comments via the pod meta:

"doc.format": "markdown"

Everything in Fantom is going to use the exact same markdown flavor we defined for Xeto as documented here. For discussion purposes since the term fandoc is already so loaded, we are using going to use the term xetodoc to mean the flavor of markdown that Fantom will use that is also the same as Xeto.

The game plan is as follows:

1. the conversion code and compiler updates are checked in if you want to play with them
2. we will perform one last build with all the docs in fandoc - 1.0.83
3. then we convert all the docs in the fantom repo to markdown going forward

Side note: for Haxall docs we are only going to support markdown starting in 4.0.6

At some point in the near future we will probably also convert all the forum posts