13

Am I able to display an asciidoc file on github in the same way that I can currently view a markdown file? According to this blog entry, I should be able to do this:

If you’re interested in using AsciiDoc, head over to GitHub and create a new file in one of your repositories or gists using the file extension .asciidoc or .adoc.

However I tried to do this and it did not work. Can anyone tell me how to get an asciidoc document to display the nicely formatted text on Github?

Here is a document that I was trying to test with Asciidoc. https://github.com/00krishna/proj_blog/blob/master/test.adoc

Vadim Kotov
  • 8,084
  • 8
  • 48
  • 62
krishnab
  • 9,270
  • 12
  • 66
  • 123

2 Answers2

13

Your file isn't syntactically valid (or rather the line is treated as plain text).

Your original file:

==This is a test
this is a test of using asciidoc

There's no space after the ==; I believe it's required.

A modified version that displays correctly:

== This is a test
this is a test of using asciidoc

See test.adoc and test2.adoc in this Gist.

The syntax for this feature, "One line titles", is documented in the Asciidoc user guide, section 11.2.

Keith Thompson
  • 254,901
  • 44
  • 429
  • 631
  • Haha, as simple as that eh. That is great. Thanks for the tips. I got it to work on github as well. – krishnab Jun 17 '15 at 23:32
  • Just to clarify. File with extension `.adoc` won't appear in Github Wiki, only `.asciidoc` works there. But when you have `.adoc` file in your repo and open it from `code browser` it will be rendered fine. – Sergey Yamshchikov Dec 06 '21 at 14:20
1

As a supplement to the accepted answer, Github (or at least the Wiki portion of Github) only accepts the .asciidoc suffix. .adoc and .ad don't seem to work. I only came upon this because I tried to manually change the pages in the wiki from .md to .ad and they wouldn't render, so check this if your problem persists.

Joseph Glover
  • 330
  • 3
  • 11
  • 1
    Perhaps `.ad` doesn't work, but `.adoc` does, at least for the examples in [my answer](https://stackoverflow.com/a/30902890/827263). – Keith Thompson Apr 16 '21 at 20:51