github-markup 1.3.3 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CONTRIBUTING.md +15 -47
- data/Gemfile +2 -2
- data/README.md +20 -36
- data/lib/github-markup.rb +1 -1
- data/lib/github/commands/rest2html +9 -1
- data/lib/github/markup.rb +2 -2
- data/lib/github/markup/command_implementation.rb +3 -2
- data/lib/github/markup/gem_implementation.rb +4 -0
- data/lib/github/markup/markdown.rb +4 -0
- data/lib/github/markup/rdoc.rb +10 -5
- data/lib/github/markups.rb +12 -8
- data/test/markup_test.rb +13 -1
- data/test/markups/README.asciidoc +10 -1
- data/test/markups/README.asciidoc.html +23 -2
- data/test/markups/README.rst +4 -0
- data/test/markups/README.rst.html +5 -1
- metadata +3 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 6e6ecef369a72fbef3cdd07bdf6da3653c43a1ba
|
4
|
+
data.tar.gz: efc6c822663fa8cab86fa7dbce03980ca8dca994
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 3da515fc4331f35270fc4ae775aa7fdf6f2c0864fe46a683fc5c95a57994f7ad8a784fa9ef8b941642a969ea22b12a1023c3cefee8226102d796a20e69468240
|
7
|
+
data.tar.gz: c4b691d2758f7c8edebf80e01af332f48766f51135973aa609f1f17a98ad76e7f40e29d4ba88b52f9210c3a731c5c771c0c3b6290f70de97c09c487bd112570a
|
data/CONTRIBUTING.md
CHANGED
@@ -1,6 +1,19 @@
|
|
1
1
|
# Contributing
|
2
2
|
|
3
|
-
|
3
|
+
This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.
|
4
|
+
[code-of-conduct]: http://todogroup.org/opencodeofconduct/#GitHub%20Markup/opensource@github.com
|
5
|
+
|
6
|
+
This library's only job is to decide which markup format to use and call out to an external library to convert the markup to HTML (see the [README](README.md) for more information on how markup is rendered on GitHub.com).
|
7
|
+
|
8
|
+
If you are having an issue with:
|
9
|
+
|
10
|
+
* **Syntax highlighting** - see [github/linguist](https://github.com/github/linguist/blob/master/CONTRIBUTING.md#fixing-syntax-highlighting)
|
11
|
+
* **Markdown on GitHub** - contact support@github.com
|
12
|
+
* **Styling issues on GitHub** - see [primer/markdown](https://github.com/primer/markdown)
|
13
|
+
|
14
|
+
Anything else - [search open issues](https://github.com/github/markup/issues) or create an issue and and we'll help point you in the right direction.
|
15
|
+
|
16
|
+
## Submitting a Pull Request
|
4
17
|
|
5
18
|
1. Fork it.
|
6
19
|
2. Create a branch (`git checkout -b my_markup`)
|
@@ -9,57 +22,12 @@ Want to contribute? Great!
|
|
9
22
|
5. Open a [Pull Request][1]
|
10
23
|
6. Enjoy a refreshing Diet Coke and wait
|
11
24
|
|
12
|
-
|
13
|
-
There are two ways to add markups.
|
14
|
-
|
15
|
-
### Commands
|
16
|
-
|
17
|
-
If your markup is in a language other than Ruby, drop a translator
|
18
|
-
script in `lib/github/commands` which accepts input on STDIN and
|
19
|
-
returns HTML on STDOUT. See [rest2html][r2h] for an example.
|
20
|
-
|
21
|
-
Once your script is in place, edit `lib/github/markups.rb` and tell
|
22
|
-
GitHub Markup about it. Again we look to [rest2html][r2hc] for
|
23
|
-
guidance:
|
24
|
-
|
25
|
-
command(:rest2html, /re?st(.txt)?/)
|
26
|
-
|
27
|
-
Here we're telling GitHub Markup of the existence of a `rest2html`
|
28
|
-
command which should be used for any file ending in `rest`,
|
29
|
-
`rst`, `rest.txt` or `rst.txt`. Any regular expression will do.
|
30
|
-
|
31
|
-
Finally add your [tests](#testing).
|
32
|
-
|
33
|
-
### Classes
|
34
|
-
|
35
|
-
If your markup can be translated using a Ruby library, that's
|
36
|
-
great. Check out `lib/github/markups.rb` for some
|
37
|
-
examples. Let's look at Markdown:
|
38
|
-
|
39
|
-
markup(:markdown, /md|mkdn?|markdown/) do |content|
|
40
|
-
Markdown.new(content).to_html
|
41
|
-
end
|
42
|
-
|
43
|
-
We give the `markup` method three bits of information: the name of the
|
44
|
-
file to `require`, a regular expression for extensions to match, and a
|
45
|
-
block to run with unformatted markup which should return HTML.
|
46
|
-
|
47
|
-
If you need to monkeypatch a RubyGem or something, check out the
|
48
|
-
included RDoc example.
|
49
|
-
|
50
|
-
Finally add your [tests](#testing).
|
51
|
-
|
52
|
-
### Testing
|
25
|
+
## Testing
|
53
26
|
|
54
27
|
To run the tests:
|
55
28
|
|
56
29
|
$ rake
|
57
30
|
|
58
|
-
When adding support for a new markup library, create a `README.extension` in `test/markups` along with a `README.extension.html`. As you may imagine, the `README.extension` should be your known input and the
|
59
|
-
`README.extension.html` should be the desired output.
|
60
|
-
|
61
|
-
Now run the tests: `rake`
|
62
|
-
|
63
31
|
If nothing complains, congratulations!
|
64
32
|
|
65
33
|
## Releasing a new version
|
data/Gemfile
CHANGED
data/README.md
CHANGED
@@ -1,8 +1,15 @@
|
|
1
1
|
GitHub Markup
|
2
2
|
=============
|
3
3
|
|
4
|
-
|
5
|
-
|
4
|
+
This library is the first step of a journey that every markup file in a repository goes on before it is rendered on GitHub.com:
|
5
|
+
|
6
|
+
0. This library converts the raw markup to HTML. See the list of [supported markup formats](#markups) below.
|
7
|
+
0. The HTML is sanitized, aggressively removing things that could harm you and your kin—such as `script` tags, inline-styles, and `class` or `id` attributes. See the [sanitization filter](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/sanitization_filter.rb) for the full whitelist.
|
8
|
+
0. Syntax highlighting is performed on code blocks. See [github/linguist](https://github.com/github/linguist#syntax-highlighting) for more information about syntax highlighting.
|
9
|
+
0. The HTML is passed through other filters in the [html-pipeline](https://github.com/jch/html-pipeline) that add special sauce, such as [emoji](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/emoji_filter.rb), [task lists](https://github.com/github/task_list/blob/master/lib/task_list/filter.rb), [named anchors](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/toc_filter.rb), [CDN caching for images](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/camo_filter.rb), and [autolinking](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/autolink_filter.rb).
|
10
|
+
0. The resulting HTML is rendered on GitHub.com.
|
11
|
+
|
12
|
+
Please see our [contributing guidelines](CONTRIBUTING.md) before reporting an issue.
|
6
13
|
|
7
14
|
Markups
|
8
15
|
-------
|
@@ -24,49 +31,26 @@ you wish to run the library. You can also run `script/bootstrap` to fetch them a
|
|
24
31
|
Installation
|
25
32
|
-----------
|
26
33
|
|
27
|
-
|
34
|
+
```
|
35
|
+
gem install github-markup
|
36
|
+
```
|
28
37
|
|
29
38
|
Usage
|
30
39
|
-----
|
31
40
|
|
32
|
-
|
33
|
-
|
41
|
+
```ruby
|
42
|
+
require 'github/markup'
|
43
|
+
GitHub::Markup.render('README.markdown', "* One\n* Two")
|
44
|
+
```
|
34
45
|
|
35
46
|
Or, more realistically:
|
36
47
|
|
37
|
-
|
38
|
-
|
48
|
+
```ruby
|
49
|
+
require 'github/markup'
|
50
|
+
GitHub::Markup.render(file, File.read(file))
|
51
|
+
```
|
39
52
|
|
40
53
|
Contributing
|
41
54
|
------------
|
42
55
|
|
43
56
|
See [Contributing](CONTRIBUTING.md)
|
44
|
-
|
45
|
-
HTML sanitization
|
46
|
-
-----------------
|
47
|
-
|
48
|
-
HTML rendered by the various markup language processors gets passed through an [HTML sanitization filter](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/sanitization_filter.rb) for security reasons. HTML elements not in the whitelist are removed. HTML attributes not in the whitelist are removed from the preserved elements.
|
49
|
-
|
50
|
-
The following HTML elements, organized by category, are whitelisted:
|
51
|
-
|
52
|
-
|Type | Elements
|
53
|
-
|------|----------
|
54
|
-
|Headings | `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `h7`, `h8`
|
55
|
-
|Prose | `p`, `div`, `blockquote`
|
56
|
-
|Formatted | `pre`
|
57
|
-
| Inline | `b`, `i`, `strong`, `em`, `tt`, `code`, `ins`, `del`, `sup`, `sub`, `kbd`, `samp`, `q`, `var`
|
58
|
-
| Lists | `ol`, `ul`, `li`, `dl`, `dt`, `dd`
|
59
|
-
| Tables | `table`, `thead`, `tbody`, `tfoot`, `tr`, `td`, `th`
|
60
|
-
| Breaks | `br`, `hr`
|
61
|
-
| Ruby (East Asian) | `ruby`, `rt`, `rp`
|
62
|
-
|
63
|
-
The following attributes, organized by element, are whitelisted:
|
64
|
-
|
65
|
-
|Element | Attributes
|
66
|
-
|------|----------
|
67
|
-
| `a` | `href` (`http://`, `https://`, `mailto://`, `github-windows://`, and `github-mac://` URI schemes and relative paths only)
|
68
|
-
| `img` | `src` (`http://` and `https://` URI schemes and relative paths only)
|
69
|
-
| `div` | `itemscope`, `itemtype`
|
70
|
-
| All | `abbr`, `accept`, `accept-charset`, `accesskey`, `action`, `align`, `alt`, `axis`, `border`, `cellpadding`, `cellspacing`, `char`, `charoff`, `charset`, `checked`, `cite`, `clear`, `cols`, `colspan`, `color`, `compact`, `coords`, `datetime`, `dir`, `disabled`, `enctype`, `for`, `frame`, `headers`, `height`, `hreflang`, `hspace`, `ismap`, `label`, `lang`, `longdesc`, `maxlength`, `media`, `method`, `multiple`, `name`, `nohref`, `noshade`, `nowrap`, `prompt`, `readonly`, `rel`, `rev`, `rows`, `rowspan`, `rules`, `scope`, `selected`, `shape`, `size`, `span`, `start`, `summary`, `tabindex`, `target`, `title`, `type`, `usemap`, `valign`, `value`, `vspace`, `width`, `itemprop`
|
71
|
-
|
72
|
-
Note that the `id` attribute is *not* whitelisted.
|
data/lib/github-markup.rb
CHANGED
@@ -44,11 +44,13 @@ except:
|
|
44
44
|
|
45
45
|
import codecs
|
46
46
|
|
47
|
+
from docutils import nodes
|
48
|
+
from docutils.parsers.rst import roles
|
47
49
|
from docutils.core import publish_parts
|
48
50
|
from docutils.writers.html4css1 import Writer, HTMLTranslator
|
49
51
|
|
50
52
|
SETTINGS = {
|
51
|
-
'cloak_email_addresses':
|
53
|
+
'cloak_email_addresses': False,
|
52
54
|
'file_insertion_enabled': False,
|
53
55
|
'raw_enabled': False,
|
54
56
|
'strip_comments': True,
|
@@ -127,6 +129,10 @@ class GitHubHTMLTranslator(HTMLTranslator):
|
|
127
129
|
self.body.append(self.starttag(node, 'img', **atts))
|
128
130
|
self.body.append(self.context.pop())
|
129
131
|
|
132
|
+
def kbd(name, rawtext, text, lineno, inliner, options=None, content=None):
|
133
|
+
|
134
|
+
return [nodes.raw('', '<kbd>%s</kbd>' % text, format='html')], []
|
135
|
+
|
130
136
|
def main():
|
131
137
|
"""
|
132
138
|
Parses the given ReST file or the redirected string input and returns the
|
@@ -145,6 +151,8 @@ def main():
|
|
145
151
|
writer = Writer()
|
146
152
|
writer.translator_class = GitHubHTMLTranslator
|
147
153
|
|
154
|
+
roles.register_canonical_role('kbd', kbd)
|
155
|
+
|
148
156
|
parts = publish_parts(text, writer=writer, settings_overrides=SETTINGS)
|
149
157
|
if 'html_body' in parts:
|
150
158
|
html = parts['html_body']
|
data/lib/github/markup.rb
CHANGED
@@ -30,12 +30,12 @@ module GitHub
|
|
30
30
|
markups << GemImplementation.new(pattern, file, &block)
|
31
31
|
end
|
32
32
|
|
33
|
-
def command(command, regexp, &block)
|
33
|
+
def command(command, regexp, name, &block)
|
34
34
|
if File.exist?(file = File.dirname(__FILE__) + "/commands/#{command}")
|
35
35
|
command = file
|
36
36
|
end
|
37
37
|
|
38
|
-
markups << CommandImplementation.new(regexp, command, &block)
|
38
|
+
markups << CommandImplementation.new(regexp, command, name, &block)
|
39
39
|
end
|
40
40
|
|
41
41
|
def can_render?(filename)
|
@@ -12,12 +12,13 @@ module GitHub
|
|
12
12
|
end
|
13
13
|
|
14
14
|
class CommandImplementation < Implementation
|
15
|
-
attr_reader :command, :block
|
15
|
+
attr_reader :command, :block, :name
|
16
16
|
|
17
|
-
def initialize(regexp, command, &block)
|
17
|
+
def initialize(regexp, command, name, &block)
|
18
18
|
super regexp
|
19
19
|
@command = command.to_s
|
20
20
|
@block = block
|
21
|
+
@name = name
|
21
22
|
end
|
22
23
|
|
23
24
|
def render(content)
|
data/lib/github/markup/rdoc.rb
CHANGED
@@ -1,20 +1,25 @@
|
|
1
|
+
require "github/markup/implementation"
|
1
2
|
require "rdoc"
|
2
3
|
require "rdoc/markup/to_html"
|
3
4
|
|
4
5
|
module GitHub
|
5
6
|
module Markup
|
6
|
-
class RDoc
|
7
|
-
def initialize
|
8
|
-
|
7
|
+
class RDoc < Implementation
|
8
|
+
def initialize
|
9
|
+
super /rdoc/
|
9
10
|
end
|
10
11
|
|
11
|
-
def
|
12
|
+
def render(content)
|
12
13
|
if ::RDoc::VERSION.to_i >= 4
|
13
14
|
h = ::RDoc::Markup::ToHtml.new(::RDoc::Options.new)
|
14
15
|
else
|
15
16
|
h = ::RDoc::Markup::ToHtml.new
|
16
17
|
end
|
17
|
-
h.convert(
|
18
|
+
h.convert(content)
|
19
|
+
end
|
20
|
+
|
21
|
+
def name
|
22
|
+
"rdoc"
|
18
23
|
end
|
19
24
|
end
|
20
25
|
end
|
data/lib/github/markups.rb
CHANGED
@@ -1,4 +1,5 @@
|
|
1
1
|
require "github/markup/markdown"
|
2
|
+
require "github/markup/rdoc"
|
2
3
|
require "shellwords"
|
3
4
|
|
4
5
|
markups << GitHub::Markup::Markdown.new
|
@@ -7,13 +8,11 @@ markup(:redcloth, /textile/) do |content|
|
|
7
8
|
RedCloth.new(content).to_html
|
8
9
|
end
|
9
10
|
|
10
|
-
|
11
|
-
GitHub::Markup::RDoc.new(content).to_html
|
12
|
-
end
|
11
|
+
markups << GitHub::Markup::RDoc.new
|
13
12
|
|
14
13
|
markup('org-ruby', /org/) do |content|
|
15
|
-
Orgmode::Parser.new(content, {
|
16
|
-
:allow_include_files => false,
|
14
|
+
Orgmode::Parser.new(content, {
|
15
|
+
:allow_include_files => false,
|
17
16
|
:skip_syntax_highlight => true
|
18
17
|
}).to_html
|
19
18
|
end
|
@@ -27,17 +26,22 @@ markup(:wikicloth, /mediawiki|wiki/) do |content|
|
|
27
26
|
end
|
28
27
|
|
29
28
|
markup(:asciidoctor, /adoc|asc(iidoc)?/) do |content|
|
30
|
-
Asciidoctor.
|
29
|
+
Asciidoctor::Compliance.unique_id_start_index = 1
|
30
|
+
Asciidoctor.convert(content, :safe => :secure, :attributes => %w(showtitle=@ idprefix idseparator=- env=github env-github source-highlighter=html-pipeline))
|
31
31
|
end
|
32
32
|
|
33
|
-
command(
|
33
|
+
command(
|
34
|
+
"python2 -S #{Shellwords.escape(File.dirname(__FILE__))}/commands/rest2html",
|
35
|
+
/re?st(\.txt)?/,
|
36
|
+
"restructuredtext"
|
37
|
+
)
|
34
38
|
|
35
39
|
# pod2html is nice enough to generate a full-on HTML document for us,
|
36
40
|
# so we return the favor by ripping out the good parts.
|
37
41
|
#
|
38
42
|
# Any block passed to `command` will be handed the command's STDOUT for
|
39
43
|
# post processing.
|
40
|
-
command('/usr/bin/env perl -MPod::Simple::HTML -e Pod::Simple::HTML::go', /pod
|
44
|
+
command('/usr/bin/env perl -MPod::Simple::HTML -e Pod::Simple::HTML::go', /pod/, "pod") do |rendered|
|
41
45
|
if rendered =~ /<!-- start doc -->\s*(.+)\s*<!-- end doc -->/mi
|
42
46
|
$1
|
43
47
|
end
|
data/test/markup_test.rb
CHANGED
@@ -85,8 +85,20 @@ message
|
|
85
85
|
assert_equal true, GitHub::Markup.can_render?('README.litcoffee')
|
86
86
|
end
|
87
87
|
|
88
|
+
def test_each_render_has_a_name
|
89
|
+
assert_equal "markdown", GitHub::Markup.renderer('README.md').name
|
90
|
+
assert_equal "redcloth", GitHub::Markup.renderer('README.textile').name
|
91
|
+
assert_equal "rdoc", GitHub::Markup.renderer('README.rdoc').name
|
92
|
+
assert_equal "org-ruby", GitHub::Markup.renderer('README.org').name
|
93
|
+
assert_equal "creole", GitHub::Markup.renderer('README.creole').name
|
94
|
+
assert_equal "wikicloth", GitHub::Markup.renderer('README.wiki').name
|
95
|
+
assert_equal "asciidoctor", GitHub::Markup.renderer('README.adoc').name
|
96
|
+
assert_equal "restructuredtext", GitHub::Markup.renderer('README.rst').name
|
97
|
+
assert_equal "pod", GitHub::Markup.renderer('README.pod').name
|
98
|
+
end
|
99
|
+
|
88
100
|
def test_raises_error_if_command_exits_non_zero
|
89
|
-
GitHub::Markup.command('test/fixtures/fail.sh', /fail
|
101
|
+
GitHub::Markup.command('test/fixtures/fail.sh', /fail/, 'fail')
|
90
102
|
assert GitHub::Markup.can_render?('README.fail')
|
91
103
|
begin
|
92
104
|
GitHub::Markup.render('README.fail', "stop swallowing errors")
|
@@ -5,10 +5,19 @@
|
|
5
5
|
* One
|
6
6
|
* Two
|
7
7
|
|
8
|
-
|
8
|
+
Refer to <<another-section>> or <<another-section-1>>.
|
9
|
+
|
10
|
+
== Another Section
|
9
11
|
|
10
12
|
NOTE: Here is some source code.
|
11
13
|
|
12
14
|
```ruby
|
13
15
|
puts "Hello, World!"
|
14
16
|
```
|
17
|
+
|
18
|
+
* [ ] todo
|
19
|
+
* [x] done
|
20
|
+
|
21
|
+
== Another Section
|
22
|
+
|
23
|
+
content
|
@@ -12,10 +12,13 @@
|
|
12
12
|
</li>
|
13
13
|
</ul>
|
14
14
|
</div>
|
15
|
+
<div>
|
16
|
+
<p>Refer to <a href="#another-section">Another Section</a> or <a href="#another-section-1">Another Section</a>.</p>
|
17
|
+
</div>
|
15
18
|
</div>
|
16
19
|
</div>
|
17
20
|
<div>
|
18
|
-
<h2>
|
21
|
+
<h2>Another Section</h2>
|
19
22
|
<div>
|
20
23
|
<div>
|
21
24
|
<table>
|
@@ -34,5 +37,23 @@ Here is some source code.
|
|
34
37
|
<pre lang="ruby"><code>puts "Hello, World!"</code></pre>
|
35
38
|
</div>
|
36
39
|
</div>
|
40
|
+
<div>
|
41
|
+
<ul>
|
42
|
+
<li>
|
43
|
+
<p>❏ todo</p>
|
44
|
+
</li>
|
45
|
+
<li>
|
46
|
+
<p>✓ done</p>
|
47
|
+
</li>
|
48
|
+
</ul>
|
49
|
+
</div>
|
50
|
+
</div>
|
51
|
+
</div>
|
52
|
+
<div>
|
53
|
+
<h2>Another Section</h2>
|
54
|
+
<div>
|
55
|
+
<div>
|
56
|
+
<p>content</p>
|
57
|
+
</div>
|
58
|
+
</div>
|
37
59
|
</div>
|
38
|
-
</div>
|
data/test/markups/README.rst
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: github-markup
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.
|
4
|
+
version: 1.4.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Chris Wanstrath
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2015-
|
11
|
+
date: 2015-07-31 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: minitest
|
@@ -162,7 +162,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
162
162
|
version: '0'
|
163
163
|
requirements: []
|
164
164
|
rubyforge_project:
|
165
|
-
rubygems_version: 2.2.
|
165
|
+
rubygems_version: 2.2.3
|
166
166
|
signing_key:
|
167
167
|
specification_version: 4
|
168
168
|
summary: The code GitHub uses to render README.markup
|