Improvements to documentation (dart-lang/markdown#397)

Documentation is added to the library statement that provides some
introduction of the library guiding a user wanting to extend the syntax.

Other minor changes:

- Add `doc/` to `.gitignore`
- Fix a link to Github Flavor that raised an unresolved doc reference in
  dartdoc.
- Ensure all references to the language are capitalised (Markdown) and
  references to the library are lowercased (markdown)
- Fix a couple of references to unexisting elements (probably leftovers
  of earlier refactorings)
- Add new line to end of `.gitignore`