Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/github/markup
Determines which markup library to use to render a content file (e.g. README) on GitHub
https://github.com/github/markup
readme
Last synced: 3 days ago
JSON representation
Determines which markup library to use to render a content file (e.g. README) on GitHub
- Host: GitHub
- URL: https://github.com/github/markup
- Owner: github
- License: mit
- Created: 2009-10-31T01:02:46.000Z (about 15 years ago)
- Default Branch: master
- Last Pushed: 2024-11-25T11:09:32.000Z (17 days ago)
- Last Synced: 2024-11-26T23:55:18.124Z (15 days ago)
- Topics: readme
- Language: Ruby
- Homepage:
- Size: 765 KB
- Stars: 5,875
- Watchers: 604
- Forks: 3,397
- Open Issues: 117
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-ruby-toolbox - Markup - Small command line tool that reads Markdown files and outputs HTML (HTML & Markup / Markup processors)
- awesome - github/markup - Determines which markup library to use to render a content file (e.g. README) on GitHub (Ruby)
- starred-awesome - markup - Determines which markup library to use to render a content file (e.g. README) on GitHub (Ruby)
- awesome-fe-resources - markup
README
GitHub Markup
=============
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:
1. `github-markup` selects an _underlying library_ to convert the raw markup to HTML. See the list of [supported markup formats](#markups) below.
1. 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.
1. Syntax highlighting is performed on code blocks. See [github/linguist](https://github.com/github/linguist#syntax-highlighting) for more information about syntax highlighting.
1. The HTML is passed through other filters that add special sauce, such as emoji, task lists, named anchors, CDN caching for images, and autolinking.
1. The resulting HTML is rendered on GitHub.com.
Please note that **only the first step** is covered by this gem — the rest happens on GitHub.com. In particular, `markup` itself does no sanitization of the resulting HTML, as it expects that to be covered by whatever pipeline is consuming the HTML.
Please see our [contributing guidelines](CONTRIBUTING.md) before reporting an issue.
Markups
-------
The following markups are supported. The dependencies listed are required if
you wish to run the library. You can also run `script/bootstrap` to fetch them all.
* [.markdown, .mdown, .mkdn, .md](http://daringfireball.net/projects/markdown/) -- `gem install commonmarker` (https://github.com/gjtorikian/commonmarker)
* [.textile](https://textile-lang.com/) -- `gem install RedCloth` (https://github.com/jgarber/redcloth)
* [.rdoc](https://ruby.github.io/rdoc/) -- `gem install rdoc -v 3.6.1`
* [.org](http://orgmode.org/) -- `gem install org-ruby` (https://github.com/wallyqs/org-ruby)
* [.creole](http://wikicreole.org/) -- `gem install creole` (https://github.com/larsch/creole)
* [.mediawiki, .wiki](http://www.mediawiki.org/wiki/Help:Formatting) -- `gem install wikicloth` (https://github.com/nricciar/wikicloth)
* [.rst](http://docutils.sourceforge.net/rst.html) -- `pip install docutils`
* [.asciidoc, .adoc, .asc](http://asciidoc.org/) -- `gem install asciidoctor` (http://asciidoctor.org)
* [.pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::XHTML`
comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
Installation
-----------
```
gem install github-markup
```
or
```
bundle install
```
from this directory.
Usage
-----
Basic form:
```ruby
require 'github/markup'
GitHub::Markup.render('README.markdown', "* One\n* Two")
```
More realistic form:
```ruby
require 'github/markup'
GitHub::Markup.render(file, File.read(file))
```
And a convenience form:
```ruby
require 'github/markup'
GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "* One\n* Two")
```
Local Development
-----------------
```sh
python3 -m venv .venv
source .venv/bin/activate
cd script
./bootstrap
```
Contributing
------------
See [Contributing](CONTRIBUTING.md).