Split gitHub into gitHubWeb and gitHubFlavored (#188)
Split gitHub into gitHubWeb and gitHubFlavored
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 34ef832..1fcb5f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,9 @@
## 1.1.0
* Make the constructor for ExtensionSet public, for tools like dartdoc.
+* Split the `gitHub` ExtensionSet into two sets: `gitHubFlavored`, which
+ represents the GitHub Flavored Markdown spec, and `gitHubWeb`, which
+ represents what GitHub actually renders Markdown.
## 1.0.0
diff --git a/README.md b/README.md
index 9970e28..dcaca0d 100644
--- a/README.md
+++ b/README.md
@@ -69,9 +69,13 @@
* `new InlineHtmlSyntax()`
* `const FencedCodeBlockSyntax()`
-* `ExtensionSet.gitHub` includes five extensions:
+* `ExtensionSet.gitHubWeb` includes five extensions:
* `new InlineHtmlSyntax()`
+ * `const HeaderWithIdSyntax()`, which adds `id` attributes to ATX-style
+ headers, for easy intra-document linking.
+ * `const SetextHeaderWithIdSyntax()`, which adds `id` attributes to
+ Setext-style headers, for easy intra-document linking.
* `const FencedCodeBlockSyntax()`
* `const TableSyntax()`
diff --git a/example/app.dart b/example/app.dart
index e0f4c53..9f7c164 100644
--- a/example/app.dart
+++ b/example/app.dart
@@ -25,7 +25,7 @@
final extensionSets = {
'basic-radio': md.ExtensionSet.none,
'commonmark-radio': md.ExtensionSet.commonMark,
- 'gfm-radio': md.ExtensionSet.gitHub,
+ 'gfm-radio': md.ExtensionSet.gitHubWeb,
};
void main() {
diff --git a/lib/src/extension_set.dart b/lib/src/extension_set.dart
index 863004f..d18337a 100644
--- a/lib/src/extension_set.dart
+++ b/lib/src/extension_set.dart
@@ -7,15 +7,51 @@
/// For example, the [gitHub] set of syntax extensions allows users to output
/// HTML from their Markdown in a similar fashion to GitHub's parsing.
class ExtensionSet {
+ /// The [none] extension set renders Markdown similar to [Markdown.pl].
+ ///
+ /// However, this set does not render _exactly_ the same as Markdown.pl;
+ /// rather it is more-or-less the CommonMark standard of Markdown, without
+ /// fenced code blocks, or inline HTML.
+ ///
+ /// [Markdown.pl]: http://daringfireball.net/projects/markdown/syntax
static final ExtensionSet none = new ExtensionSet([], []);
+ /// The [commonMark] extension set is close to compliance with [CommonMark].
+ ///
+ /// [CommonMark]: http://commonmark.org/
static final ExtensionSet commonMark = new ExtensionSet(
[const FencedCodeBlockSyntax()], [new InlineHtmlSyntax()]);
- static final ExtensionSet gitHub = new ExtensionSet(
+ /// The [gitHubWeb] extension set renders Markdown similarly to GitHub.
+ ///
+ /// This is different from the [gitHubFlavored] extension set in that GitHub
+ /// actually renders HTML different from straight [GitHub flavored Markdown].
+ ///
+ /// (The only difference currently is that [gitHubWeb] renders headers with
+ /// linkable IDs.)
+ ///
+ /// [GitHub flavored Markdown]: https://github.github.com/gfm/
+ static final ExtensionSet gitHubWeb = new ExtensionSet([
+ const FencedCodeBlockSyntax(),
+ const HeaderWithIdSyntax(),
+ const SetextHeaderWithIdSyntax(),
+ const TableSyntax()
+ ], [
+ new InlineHtmlSyntax()
+ ]);
+
+ /// The [gitHubFlavored] extension set is close to compliance with the [GitHub
+ /// flavored Markdown spec].
+ ///
+ /// [GitHub flavored Markdown]: https://github.github.com/gfm/
+ static final ExtensionSet gitHubFlavored = new ExtensionSet(
[const FencedCodeBlockSyntax(), const TableSyntax()],
[new InlineHtmlSyntax()]);
+ /// The deprecated name for the [gitHubFlavored] extension set.
+ @deprecated
+ static final ExtensionSet gitHub = gitHubFlavored;
+
final List<BlockSyntax> blockSyntaxes;
final List<InlineSyntax> inlineSyntaxes;
diff --git a/tool/stats_lib.dart b/tool/stats_lib.dart
index 8d06e79..15290aa 100644
--- a/tool/stats_lib.dart
+++ b/tool/stats_lib.dart
@@ -45,7 +45,7 @@
static final Config commonMarkConfig =
new Config._('common_mark', 'http://spec.commonmark.org/0.28/', null);
static final Config gfmConfig = new Config._(
- 'gfm', 'https://github.github.com/gfm/', ExtensionSet.gitHub);
+ 'gfm', 'https://github.github.com/gfm/', ExtensionSet.gitHubFlavored);
final String prefix;
final String baseUrl;
