GitHub uses following line, I presume:

rst2html.py README.rst > README.html

which if you ask me is incorrect, it causes two H1 to appear. Instead please make an option if not default to be able to use this:

rst2html.py --no-doc-title README.rst > README.html

The name implies that it drops title, that is not correct it just makes the Header levels correct, using that there is only one H1.

And it should be github's.

http://msdn.microsoft.com/en-us/library/cc351024(v=vs.85).aspx

link containing ( and ) is broken.

In Perl versions earlier than 5.10, you need to install Pod::Simple from CPAN.

If the mediawiki parser sees more than four sections in the current mediawiki document it automatically renders a TOC. As this behaviour is not consistent across all parsers (only mediawiki does this), it should be turned off by default.

One way is to pass the NOTOC markup along with the page content

markup(:wikicloth, /mediawiki|wiki/) do |content|
  WikiCloth::WikiCloth.new(:data => "__NOTOC__" + content).to_html(:noedit => true)
end

But there's probably a better way to do this...

I wrote a nokogiri based TOC generator that could be easily integrated if such functionality is needed:
https://github.com/arr2036/gollum/blob/toc_extension/lib/extensions/toc.rb

There seems to be a problem with Ruby's open3 or the operating system's pipe buffer that causes a puts of more than 65,535 bytes to hang open3. The following code does basically the same thing markup does:

#!/usr/bin/ruby

require 'open3'

command = "cat"
target  = "x" * 65535
out     = ""

Open3.popen3(command) do |stdin, stdout, _|
    stdin.puts target
    stdin.close
    out = stdout.read
end

puts out.length

target  = "x" * 65536
out     = ""

puts "1"
Open3.popen3(command) do |stdin, stdout, _|
    puts "2"
    stdin.puts target
    puts "3"
    stdin.close
    out = stdout.read
end

puts out.length

Doing this because i play all musical instruments too well for anyone to have me play and overshadow them. o I figure if I can get good at this then I might be able to make musical codes.
NEED TO KNOW WHERE IS A GOOD POINT TO START FROM, WILLING TO LEARN MORE THAN A DOCTOR ON THE ENTERPRISE

See http://github.com/dp-/tcx2web for an example - the closing > is incorrectly treated as part of the link.

sorry, #17 is correct.

Configure Ruby for madvertise via Gemcutter

I can't seem to find a connection between GitHub's markup support and GitHub Flavored Markdown anywhere. It'd be nice to have though. Even if it uses a new .gfm extension so it doesn't break existing .md README files.

Does it not exist because it ties repos to GitHub?

I find myself often converting trac projects to github, and there's a lot of wiki pages. To date I've been converting the trac pages to something Github supports, but having github support the trac wiki format might be easier for a lot of projects.

Would you be interested in a program to handle trac?

I am having trouble with inline html tags in my README.md file.

From what I have read about Daring Fireball's Markdown, Redcarpet and Upskirt, a simple span element should suffice for adding styles, like this.

<span style="color:#F00;background-color:#555">TODO</span>: Fix inline-html in README.md

However, these tags are removed from html output. What am I missing?

Thanks, -S.

Check out http://github.com/bdewey/github-markup/commit/c9aa51126cc248d6dcf8f247cda75275974785c9

Uses org-ruby to add org-mode support for README.org.

Markdown can be turned off by surrounding the content in a

creole is a wiki format designed by committee. What could be better?

In it's defence the committee process was a bit like the microformats process: balancing the features and syntaxes of exiting wiki markups to produce one that is as lacking in eccentricity as possible.

Here's my fork of markup

Is there any chance that markup and gollum will have equal features/syntax.
For example I'm really missing the ``` syntax in markup, so we could use it in READMEs.
Additionally allowing GitHub flavored Markdown everywhere would be great too.

The best alternative seems to be integrating Markup into Gollum, although this is non-trivial for sure. Maybe there are even reasons that completely prevent such an integration.

Markdown's install command (gem install markdown) and Org-mode's install command (gem install org-mode) don't work on a relatively clean install of OS X 10.6.4. Out put is as follows:

cowens@amans:~$ gem install markdown
ERROR:  Could not find a valid gem 'markdown' (>= 0) in any repository 
cowens@amans:~$ gem install org-mode
ERROR:  Could not find a valid gem 'org-mode' (>= 0) in any repository

see https://github.com/decitrig/GWT-Foo/blob/master/README.textile

.h1 header

should render

header

Would it be feasible to set the asciidoc theme or include custom stylesheet?

I realize that it would be most undesirable to have side effects to any elements outside of div.wikistyle but I guess it could be possible hopeful

It's somewhat common especially for Perl projects to have POD markdown in a README file without a .pod extension, here's one example of this.

The simplest way to support this would be to simply shell out to file(1) for README files:

v rakudo (master) $ file README 
README: Perl POD document text

Example in the wild: http://github.com/icco/Resume/blob/master/README.md

Mixing and matching <ol> and <ul> in markdown fails kind of epicly.

Local example:

    1. a
        * b
    2. c

which the markdown dingus says should be rendered as

1. a
   
   • b


2. c

but you render as a single <ol>.

http://github.com/rtomayko/ronn
http://github.com/sfiera/github-markup/tree/ronn

As stated in the commit message, this is missing an appropriate stylesheet. I don't know what the preferred method for fixing that is; style information must go in , but there isn't a hook for that exposed in the markup module, nor do I know if such a thing would be practical within the github infrastructure.

From the looks of it, hpricot would make it relatively easy to compose the stylesheet with the HTML, but it's enough work that I'd prefer to see if there's another way first.

If I have

Foo

code

Bar

• list1

• list2

  Rails.application.routes.draw do
  resource :foo
  end

Notice that the Rails.application.routes is not recognized as code. However both code and Rails.application.routes.draw ... are indented four spaces.

I used markdown to make the readme for my app, both dingus and GFM translate it right but the readme is bad. The problem is with nested ordered lists, it gets plain.
The file is in: olvap/representaciones@24d69d2

And I would like the gfm to be supported for Readme also.

Using the described greater-than symbol isn't working as it should to create a blockquote element.

This may be in the wrong issue queue; if so, I apologize in advance, and humbly request to be redirected to the proper facility.

I've discovered to my chagrin that README* files which are symlinks do not get recognized by github, or at least they are not being displayed as the README file for the branch page.

This would be quite useful, since I usually write my documentation in markdown, but for some projects, e.g. Python modules, it's important to have a README file with a name other than README.markdown. Since markdown is text, ln -s README.txt README.markdown && git add README.markdown would work quite well, except that the markup system doesn't seem to follow symlinks.

I guess I could rebuild (i.e. copy) the README.txt file in a commit/merge hook, but it's sort of a hassle to have to write a commit hook to do this, and it's somewhat confusing for people to have two files in their cloned repo or download which are exactly the same. It's also in violation, I'm sure, of some fundamental rule of source control management theory, the one about not committing generated files.

This issue is related to issue 3, in that if that feature were implemented in a way that allowed for reliable detection of markdown within *.txt files it wouldn't be necessary. It's not really clear that that's possible, though, and assuming that somebody is writing markdown when they just want their file displayed as plain text would be an annoying way to do things.

That issue is also related because somebody mentioned this approach in a comment on the issue.

There was also a suggestion made to allow the repo maintainer to indicate what format the README should be parsed as; this was responded to to the effect that such a feature was unlikely to be put into place because it "gains nothing over just adding the correct extension." Hopefully my above statements serve as a sensible objection to this assertion.

Another option, not mentioned in the comments thread for that issue, could be to use a metadata file in the repo to save github-related options, e.g. /.github:

[README]
        file = README.txt
        format = markdown

I leave it to your graces to make a wise ruling on this matter.

Altough a

Sorry, wrong project

when editing a github wiki page, the & lt ; and & gt ; html entities get converted to their corresponding characters.

to reproduce try this:

edit or add a wiki page, and add & lt ; (without spaces) in it.
press 'update' and it will look alright. now press 'edit' again. instead of & lt ; you'll have the less than character, which is not what you entered initially. probably needs html escaping between the textarea tags.

In my markup_tested branch I am allowing the testsuite to only test one markup via env var.

Link to branch: http://github.com/tilsammans/markup/tree/markup_tested

Example usage:

MARKUP=rdoc rake test

see sinatra/sinatra#189

Anchors are great for usability in long documentation.

# Install
blah blah

<h1 name="INSTALL">Install</h1>
<p>blah blah</p>

http://github.com/user/repo#INSTALL

RDoc is not rendered when using Ruby 1.9.2, even if the rdoc gem is properly installed. This can be reproduced with a call to:

GitHub::Markup.render("foo.rdoc")

Assuming foo.rdoc exists and the rdoc gem is installed, this will render the RDoc to HTML in Ruby 1.8.7. But in Ruby 1.9.2, this will just return the original RDoc text.

It looks like SM::SimpleMarkup is not available in Ruby 1.9.2 (is a new gem needed?). Possibly RDoc::Markup::ToHtml could be used instead. I'd be happy to contribute a patch if you are interested in having this fixed. Please let me know.

open php with github...?! confuse...

There is a problem with reStructuredText files (.rst) not displaying in the code browser. reStructuredText is just a text format, I know it's not markdown but they are just plain text (like markdown) so the content should at least be displayed if it cant be rendered. Normally what happens is parts of the file are simply omitted. I think what really should happen, at the least, is that they are treated as normal text files with all the content shown.

I give an extreme example of what's happening: https://github.com/doctrine/orm-documentation/blob/master/en/index.rst
Notice file has 67 lines, but github's viewer just shows 7 lines.

For reference, reStructuredText - http://docutils.sourceforge.net/rst.html
Used by Sphinx document generator - http://sphinx.pocoo.org/

The reason OSS projects use .rst files is because it's more or less like Markdown but it can be used to generated structured documentation with TOC/Index/Search etc with zero extra cost. I'm not asking that you guys render it, but at least display the content in the repo viewer.

(It doesn't look like this is part of the github/markup code, so I couldn't patch this)

Currently a lot of projects have some sort of embedded documentation that's easy to find, but GitHub doesn't find and display it.

Examples include:

• This project, which has only a single file, which includes embedded POD.
• This project. Which has a README.pod generated from lib/Hailo.pm

It would be nice if GitHub's logic for finding documentation to display in the main page of the project was a bit more permissive than just displaying glob("README_"). E.g. by seeing that the project has one main file that has embedded docs, or that the "main module" of a project has docs (e.g. for Perl code figure out that it's the top-level class in lib/, which could be just find lib -type f -name '_.pm' | head -n 1 for the common case).

I would like to be able to use Redcarpet (1 and 2) for the repos README's as well. Is this something under consideration?

You have an encoding issue regarding filenames. Files with names containing certain letters (my problem was with the danish 'ø') and files placed in folders containing such letters, will not have markdown applied to them. The markdown source is shown instead.

When running github-markup and piping into an HTML file locally the table of contents works correctly, however when published into the repository, the IDs for the anchors are removed, causing the links to do nothing!

See https://github.com/glenjamin/nodespec for an example.

This may be in the wrong issue queue; if so, I apologize in advance, and humbly request to be redirected to the proper facility.

I've discovered to my chagrin that README* files which are symlinks do not get recognized by github, or at least they are not being displayed as the README file for the branch page.

This would be quite useful, since I usually write my documentation in markdown, but for some projects, e.g. Python modules, it's important to have a README file with a name other than README.markdown. Since markdown is text, ln -s README.txt README.markdown && git add README.markdown would work quite well, except that the github web system doesn't seem to follow symlinks.

I guess I could rebuild (i.e. copy) the README.txt file in a commit/merge hook, but it's sort of a hassle to have to write a commit hook to do this, and it's somewhat confusing for people to have two files in their cloned repo or download which are exactly the same. It's also in violation, I'm sure, of some fundamental rule of source control management theory, the one about not committing generated files.

This issue is related to issue #3, in that if that feature were implemented in a way that allowed for reliable detection of markdown within *.txt files it wouldn't be necessary. It's not really clear that that's possible, though, and assuming that somebody is writing markdown when they just want their file displayed as plain text would be an annoying way to do things.

That issue is also related because somebody mentioned this approach in a comment on the issue.

There was also a suggestion made to allow the repo maintainer to indicate what format the README should be parsed as; this was responded to to the effect that such a feature was unlikely to be put into place because it "gains nothing over just adding the correct extension." Hopefully my above statements serve as a sensible objection to this assertion.

Another option, not mentioned in the comments thread for that issue, could be to use a metadata file in the repo to save github-related options, e.g. /.github:

[README]
        file = README.txt
        format = markdown

I leave it to your graces to make a wise ruling on this matter.

asciidoc readme files do not render the document header correctly. example

According to the asciidoc cheat sheet, the document header is supposed to be specified like this:

Main Header Here
================

In a github readme, the header just disappears completely instead of showing up in large title font.

Nested lists seem to be creating problems.
For example:-
The lists under the heading Usage are not rendered properly.
http://github.com/punchagan/org2blog/raw/master/README.org
http://github.com/punchagan/org2blog/blob/master/README.org

Purpose: To render cloned Google Code wiki repositories on Github.

Problem: Missing MoinMoin wiki parser.

Workaround: To render a MoinMoin wiki page into rst via moin2rst.

• http://moinmo.in/HelpOnMoinWikiSyntax
• http://moinmo.in/FormatterMarket
• http://www.merten-home.de/FreeSoftware/moin2rst/
• http://code.google.com/p/support/wiki/WikiFAQ
• http://code.google.com/p/support/wiki/WikiSyntax

https://gist.github.com/835947

Issue present both on ree and rbx. Rubygems 1.5.2, other gems work.

I just added some support for Maruku: Wilhansen/markup@039f72d690ca1ad9a17b

Ideally, markup would have some configuration mechanism that allows one to override which processor to use for what file format. Unfortunately, that might require a non-trivial overhaul so what I did was just to add another file extension, *.maruku.

hi,

could you add support for pandoc markdown1? it has some extra features like definition lists, which are useful for README documentation.

to distinguish between pandoc markdown and regular markdown, you could note the pandoc support for document metadata ("title blocks"2) which makes the file start with '%', an extremely unusual first character for a regular markdown document.

http://github.com/tekkub/github-markup/commit/5f8024f46176541b74346095e8f122bf8d968b44

I'm working on a documentation project that uses Sphinx + RestructuredText. See e.g.:

https://github.com/python4astronomers/python4astronomers/blob/master/source/installation/installation.rst

The problem is that in this case I do not want to have the *.rst files automatically rendered to HTML, instead I want to see the raw RestructuredText. I hope I'm not missing something obvious but I cannot see a way to just see the raw file content. The "raw" button is quite a tease since it looks like what I want but it just gives me a file download.

Thanks, Tom