5 ms·
Show HN: Instant documentation site for Github projects
- jeromegn 15y agoI needed it for one of my projects and so I whipped up this simple documentation generator. It takes your README.md and turns it into an easier to navigate documentation site. Meant to be used on a gh-pages branch. There's still much to do. This is an MVP.
- sequoia 15y agoThis is pretty cool and I know non-javascript users (besides some screen readers) aren't as common but you've gotta give something to people w/o JS, even if it's just "Please turn on javascript. Read text version here a:github.com/user/project/README.md" or something. I understand modern web apps not always degrading but this is almost 100% flat text, there should be some way to serve all users. Looks nice tho!!
- jeromegn 15y agoGood point. Noted here: https://github.com/jeromegn/DocumentUp/issues/2 https://github.com/jeromegn/DocumentUp/issues/2
- sequoia 15y agoOh, also, what do you mean by "deep linking"? I'm not sure what you'd deep-link to... is anything loaded dynamically?
- jeromegn 15y agoI mean, being able to link to a specific point (like a H2 or H3) in the README and have the page actually scroll there. Right now I don't think it works (or at least it's completely untested.)
- LeafStorm 15y agoOne nice thing about GitHub and Bitbucket's focus on the project's README is that more software projects are providing a good, instantly-readable summary of their project in the README instead of making you have to go elsewhere to find out what it's all about and how to get started. One not-so-nice thing about GitHub and Bitbucket's focus on the project's README is that I have noticed several projects that dump all their project's documentation into the README and the examples instead of having proper narrative and API documentation.
- ricardobeat 15y agoI prefer all-encompassing READMEs over incomplete scattered documentation.
- stock_toaster 15y agoI think all-in-one-README works well for some things, but some of our projects at work would result in HUUUGE readme files. Not so pleasant if those were a single file. We have started using gollum-site[1] for our stuff that grows beyond a medium size length. The single-long-readme length issue appears to be alleviated by the nav construction in documentup though. Pretty slick. https://github.com/dreverri/gollum-site https://github.com/dreverri/gollum-site
- code_pockets 15y agoAgreed, though I'm guilty as charged. This has led me to re-think the README/documentation problem, and gave me an app idea. A little web app that allows the user to build a proper README with a template. Sort of those build a resume apps, but for README files. I plan on building it at the end of February, after I ship my current foss project.
- conesus 15y agoHeard about this on Twitter, and in under 3 minutes had this: http://samuelclay.github.com/NewsBlur http://samuelclay.github.com/NewsBlur. Gorgeous and very easy to install. Kudos!
- acdha 15y agoIf you're looking for a more mature service, particularly if you're already using Sphinx, checkout http://readthedocs.org/ http://readthedocs.org/ which includes nice things like full text search, PDF generation, versioning, etc. and supports other hosting sites and version control systems.
- Klonoar 15y agoWhy doesn't github just do this themselves
- lux 15y agoCool, but the menu gets in your way when you zoom on iPhone.
- kmfrk 15y agoAre you considering adding SmartyPants to the formatting? Then again, SmartyPants takes options for which kind of formatting you want to use, and, at least in the Python version, I never go with the default one, so it's probably useless to me without the ability to specify my specific formatting. I really hope this gets a lot of attention; it's one of the best things I have seen on Hacker News in months, and I'm surprised we haven't even hit triple-digit karma for it.
- hugues 15y agoGreat project, easy to install, beautiful presentation. Why limiting to GH pages though? I would love to use it with my markdown documentation, but my project is not on github.
- shpoonj 15y agoThis would be great if it had a reliable style sheet. This one, however, breaks on iOS, for example. May I recommend BS2?
- skeptical 15y agoThis adds side navigation to README's header structure. I'm sorry if I sound negative, but I don't find this of much value. As mentioned by other users, readme files are not suposed to contain a big bulk of documentation, and they already support formatting anyway. Github also offers per project wikis and sites (which this is based on). Do we really need such a tool just to generate an index? Wouldn't this make more sense as a bookmarklet for those who want it?
- huguesalary 15y agoGreat project, easy to install, beautiful presentation. Why limiting to GH pages though? I would love to use it with my markdown documentation, but my project is not on github.
- jeromegn 15y agoI'm thinking of adding an option to Bring Your Own Markdown. This has a few implications that I need to code for though.