search

mysociety / alaveteli-experiments

A collection of experiments and research to learn about what makes an Alaveteli grow
3 stars 0 forks source link

Enable local Jekyll use for checking page layouts #15

Closed lizconlan closed 8 years ago

lizconlan commented 8 years ago

Has been a bit of a blocker for me that I can't check the files I'm working on locally to see if they're looking ok (particularly when messing about with tables and when I was trying to work out how to lay out the top social media sites per country. So I've had a go at doing this so that I can run it through Jekyll.

Adds some basic Jekyll config, an ignore file for the generated files directory and a layout that borrows just enough of the GitHub HTML (and all of the CSS - sorry GitHub) to make the pages make sense on their own. And a plugin so that we don't have to put yaml headers in the top of the markdown files as GitHub interprets this a table in the file view layout.

Assumes the markdown files will always have the .md extension otherwise the plugin won't work.

One remaining oddity is that the README page links will still point to the .md documents so it won't act as an index for the generated pages. It's probably fixable but at this point it doesn't feel like it's worth the effort (to me anyway).

I've published the plugin separately here https://github.com/lizconlan/jekyll-no-frontmatter but I'm more than happy to move it to the mySociety GitHub (just thought that was a bad starting point for a potentially silly plugin, I passed the point of "this is either a brilliant idea or the most stupid thing ever" some time ago, it can stay where it is if it's the latter).

Closes #14

garethrees commented 8 years ago

Thanks for having a go at this, but having tried it I just get a Forbidden message:

Forbidden

no access permission to `/'

I think there are plenty of existing options for rendering GFM that its not worth the hassle of maintaining a Jekyll install here.

lizconlan commented 8 years ago

Have you updated your Jekyll yet @garethrees - I seem to remember you having problems with local copies of docs as well

lizconlan commented 8 years ago

We should recommend using gfm-preview instead as it seems to be the simplest command line tool - the reason for trying to use Jekyll was the assumption that anyone working on this would already have that installed and be familiar with it to work on our documentation files.

But as gfm-preview has the same core requirements (Ruby 2+ and the ability to install gems) - and is simpler - it's probably a better bet. Switching between Ruby and Python or trying to set up a node server isn't going to be a helpful route to non dev contributors.