Merge pull request #60 from cirosantilli/contributing-guidelines

Added contributing guidelines and started tests as required by them

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644 (file)
index 0000000..d6716ce
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,49 @@
+These contributing guidelines were accepted rather late in the history of this plugin, after much code had already been written.
+
+If you find any existing behavior which does not conform to these guidelines, please correct it and send a pull request.
+
+# General Rules
+
+Every non local identifier must start with `g:vim_markdown_`.
+
+# Documentation
+
+Every new feature must be documented under in the [README.md](README.md). Documentation must be written in [GFM](https://help.github.com/articles/github-flavored-markdown) since Github itself is the primary to HTML converter used. In particular, remember that GFM adds line breaks at single newlines, so just forget about the 70 characters wide rule.
+
+# Markdown Flavors
+
+There are many flavors of markdown, each one with an unique feature set. This plugin uses the following strategy to deal with all those flavors:
+
+- Features from the [original markdown](http://daringfireball.net/projects/markdown/syntax) are turned on by default. They may not even have an option that turns them off.
+
+- Features from other markdown flavors *must* have an option that turns them on or off. If the feature is common enough across multiple versions of markdown, it may be turned on by default. This shall be decided by the community when the merge request is done.
+
+- If possible, cite the exact point in the documentation of the flavor where a feature is specified. If the feature is not documented, you may also reference the source code itself of the implementation. This way, people who do not know that flavor can check if your implementation is correct.
+
+- Do not use the name of a flavor for a feature that is used across multiple flavors. Instead, create a separate flavor option, that automatically sets each feature.
+
+    For example, fenced code blocks (putting code between pairs of three backticks) is not part of the original markdown, but is supported by [GFM](https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks) and [Jekyll](http://jekyllrb.com/docs/configuration/).
+
+    Therefore, instead of creating an option `g:vim_markdown_gfm_fenced_code_block`, and an option `g:vim_markdown_jekyll_fenced_code_block`, create a single option `g:vim_markdown_fenced_code_block`.
+
+    Next, if there are many more than one Jekyll feature options, create a `g:vim_markdown_jekyll` option that turns them all on at once.
+
+# Tests
+
+All new features must have tests. While we don't require unit tests, which are too hard to do in certain cases, you should create a test under the `test/` directory with a predictable name which allows other users to quickly test your feature. Good tests should explain their expected input / output behavior. Failing test should be marked with `FAIL` somewhere near the test, possibly explaining why it fails. For example:
+
+```
+## Links
+
+[Link text](link URL)
+
+... more correct link tests ...
+
+###### FAIL: should not be highlighted as a link
+
+Text (with parenthesis) alone should not be highlighted as a link. (Issue #57)
+
+... more failed link tests ...
+
+## Code Blocks
+```

diff --git a/README.md b/README.md
index d95bc2c389f4bf21949c1da4a90153b61bd29d2f..b72e6aeed11f877b717042ac5e39612185b84a52 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Markdown Vim Mode
 
-Syntax highlighting, matching rules and mappings for [Markdown](http://daringfireball.net/projects/markdown/).
+Syntax highlighting, matching rules and mappings for [the original Markdown](http://daringfireball.net/projects/markdown/) and extensions.
 
 ## Installation
 
@@ -28,9 +28,7 @@ let g:vim_markdown_folding_disabled=1
 
 **Set Initial Foldlevel**
 
-Add the following line to your `.vimrc` to set the initial foldlevel.  This
-option defaults to 0 (i.e. all folds are closed) and is ignored if folding
-is disabled.
+Add the following line to your `.vimrc` to set the initial foldlevel. This option defaults to 0 (i.e. all folds are closed) and is ignored if folding is disabled.
 
 ```vim
 let g:vim_markdown_initial_foldlevel=1

diff --git a/test/syntax.md b/test/syntax.md
new file mode 100644 (file)
index 0000000..8a7421d
--- /dev/null
+++ b/test/syntax.md
@@ -0,0 +1,149 @@
+# Original markdown
+
+This section covers only features from the [original markdown](daringfireball.net/projects/markdown/syntax), in the same order that they are defined on the specification.
+
+Extensions will be tested on a separate section.
+
+## Paragraphs
+
+Paragraph.
+
+Line  
+break.
+
+## Headers
+
+The following should be highlighted as headers:
+
+# h1
+
+ # h1
+
+# h1 #
+
+h1
+==
+
+## h2
+
+## h2 ##
+
+h2
+--
+
+### h3
+
+#### h4
+
+##### h5
+
+###### h6
+
+The following is unspecified by Markdown and may not highlight properly:
+
+####### h7
+
+## Blockquotes
+
+> Block quote
+
+> First line only
+block quote
+
+> Block quote
+> > Block quote level 2
+
+> # Markdown inside block quote
+>
+> [Link text](link-url)
+
+## Lists
+
+Only the list marker should be highlighted:
+
+* 0
+* 1
+
++ 0
++ 1
+
+- 0
+- 1
+
+1. 0
+2. 1
+
+*Not* lists:
+
+1 0
+
+ - 0
+
+## Links
+
+[Link text](link-url)
+
+Reference style link: [Link text][reference]
+
+With space: [Link text] [reference]
+
+[reference]: address
+[reference2]: address "Optional Title"
+
+## Code blocks
+
+Inline: `inline code`
+
+Indented:
+
+    indented code block
+
+    # not a header
+
+    - not a list
+
+Indented code block and lists:
+
+- 0
+
+    Paragraph.
+
+        indented code block inside list
+
+- 0
+
+    - 1
+
+        Paragraph (TODO FAIL).
+
+            indented code block inside list
+
+## Emphasis
+
+The following should be italicized:
+
+*single asterisks*
+
+_single underscores_
+
+The following should be boldface:
+
+**double asterisks**
+
+__double underscores__
+
+# Extensions
+
+Fenced code blocks TODO add option to turn ON/OFF:
+
+```
+fenced code block
+```
+
+Fenced code block with language:
+
+```ruby
+def f
+  0
+end
+```