API Blueprint on GitHub as a first-class citizen

[honzajavorek]

Just an idea.

Now all blueprint files are superset of GitHub Flavored Markdown, so they're obviously quite well displayed on GitHub out of the box.

However, if direct support for API Blueprint was added to github/markup, it would be possible to display blueprint-specific parts (such as endpoints, etc.) nicer than now and blueprints would be even more something like first-class citizens here on GitHub.

Possible problems:

• blueprint files would probably need to have a different extension, because parsers in github/markup are most likely binded by extensions and .md are already binded to the pure Markdown parser (and having a different extension undermines some of the pros of being fully compatible with Markdown)
• the output would have to fit within allowed HTML elements, so probably no rich styling could apply anyway :-(

Another idea I came up with is to ask GitHub whether they wouldn't like to bake the direct support in themselves (maybe after the API Blueprint earns notable traction). Then it could be implemented in a similar way as GeoJSON or 3D objects, I suppose.

[zdne]

@honzajavorek

This is a neat idea. Currently API Blueprint format uses the .apib extension. For the start it would be suffice to just map the .apib to GH markdown parser (Redcarpet) in the github/markup. This should be quite straightforward.

Additional formatting à la GeoJSON would be great but that is a much bigger effort. Nonetheless it is worth exploring both improving the github/markup integration as well as possible direct support on GH.

[zdne]

Note I have created a PR on github/markup to render API Blueprint as Markdown on GitHub – github/markup#252

[zdne]

Update: The github/markup#252 was rejected by GitHub:

I think we're going to hold off on this for now. Let's revisit it in a few months and see what adoption looks like and if anyone is interested in implementing some really great styles for it.

[ryanmmmmm]

why not just also copy .apib file to README.md if the user selects that option in apiary and commit that to the repository as well as the .apid file?

[monsendag]

How about .apib.md? That would be parsed as markdown by default, but can be detected as api blueprint by supporting parsers.

[zdne]

We would still like GitHub to render blueprints correctly. @danielgtaylor may do some research on this

[monsendag]

I understand. I still think that the extension should be suffixed by .md. as it allows for a more graceful degradation.

[zdne]

As @danielgtaylor pointed out to me offline we may start with https://github.com/github/linguist/blob/master/CONTRIBUTING.md#adding-a-language I consider adding .md as the last resort option.

Or precisely I would go for it if we should fail this time (hope not :)

[danielgtaylor]

I've now opened github-linguist/linguist#2363 to add support for recognizing and highlighting .apib files on GitHub.

[zdne]

👍

[pksunkara]

API Blueprint is now first-class citizen on Github.

[zdne]

@pksunkara we haven't a) announced this yet and b) this issue was more about rendering the blueprint (not just syntax highlighting).

Either way OK to leave it as closed. I will update this once we announce it.

[honzajavorek]

Yay! 👍