GitHub already renders markdown nicely. So if we just write our website sources in Markdown, they can be easily read in the source repo and we can use them to generate our site (look at the sources for the AsterixDB site as an example). So doing this would give us a way to look at the docs in GitHub, but not an additional GitHub site.
If I understand this correctly, then we could use Jekyll to build a full GitHub site. But I don’t know if we could use the same sources to have Jekyll build a GitHub site and maven build our ASF site. But I think that it might be a good first step to translate out APT sources into Markdown sources. That seems to have a number of advantages and no real drawbacks (expect that it has to be done …). > On Jun 24, 2015, at 12:12 PM, Ian Maxon <[email protected]> wrote: > > Github pages uses Jekyll, which is a static site generator. Basically > you give markdown, and it renders that to markup, and provides > variables and ways to insert headers and footers. It's pretty nifty, I > think it's really taken off ever since Github adopted it. The > documentation is pretty good ( http://jekyllrb.com/docs/home/ ), and > there's really no lack of tutorials and templates out there as well. > It's what I used to make the new AsterixDB website, and what Flink > uses for their website as well. > > - Ian > > On Wed, Jun 24, 2015 at 10:42 AM, Jochen Wiedmann > <[email protected]> wrote: >> Are ou referring to the gh-pages brach? AFAIK, that requires basic >> HTML files. I typically use Maven to create a site. >> >> >> >> On Tue, Jun 23, 2015 at 9:22 PM, Preston Carman <[email protected]> wrote: >>> With GSOC, we are using github for code reviews and accepting work into >>> VXQuery. Is there a way to store our website documentation so that it can >>> double for easy viewing on github? Is there a tool/file format for building >>> websites that is github friendly? >> >> >> >> -- >> Any world that can produce the Taj Mahal, William Shakespeare, >> and Stripe toothpaste can't be all bad. (C.R. MacNamara, One Two Three)
