diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | Gruntfile.js | 85 | ||||
| -rw-r--r-- | README.md | 66 | ||||
| -rw-r--r-- | _config.yml | 1 | ||||
| -rw-r--r-- | package.json | 16 |
5 files changed, 165 insertions, 4 deletions
diff --git a/.gitignore b/.gitignore index 49eac9d72..aa715b2b1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .sass-cache/ _site/ +node_modules/ diff --git a/Gruntfile.js b/Gruntfile.js new file mode 100644 index 000000000..f3befd3f6 --- /dev/null +++ b/Gruntfile.js @@ -0,0 +1,85 @@ +module.exports = function(grunt) { + + // Project configuration. + grunt.initConfig({ + pkg: grunt.file.readJSON('package.json'), + + jekyll: { site: {} }, + + connect: { + server: { + options: { + base: "_site", + port: 4000, + livereload: true + } + } + }, + + uglify: { + library: { + files: { + 'assets/scripts/lib.min.js': [ + 'bower_components/jquery/jquery.js', + 'bower_components/jquery/jquery-migrate.js', + 'bower_components/owlcarousel/owl-carousel/owl.carousel.js' + ], + } + }, + main: { + files: { + 'assets/scripts/app.min.js': 'assets/scripts/app.js' + } + }, + }, + + sass: { + global: { + options: { style: 'compressed' }, + files: { + 'assets/css/global.css': 'theme/sass/global.scss', + 'assets/css/alaveteli-org.css': 'assets/sass/alaveteli-org.scss' + } + } + }, + + watch: { + options: { atBegin: true, }, + css: { + files: [ + 'assets/**/*.scss', + 'theme/**/*.scss', + ], + tasks: [ 'sass' ], + }, + js: { + files: [ + 'assets/scripts/app.js' + ], + tasks: [ 'uglify' ], + }, + jekyll: { + files: [ 'assets/**', '**/*.html', '**/*.md', '!node_modules/**', '!bower_components/**', '!_site/**' ], + tasks: [ 'jekyll' ], + }, + livereload: { + options: { atBegin: false, livereload: true, }, + // Look for Jekyll file changes, and changes to static assets + // Ignore SCSS so that live CSS update can work properly + files: [ 'assets/**', '**/*.html', '**/*.md', '!node_modules/**', '!bower_components/**', '!_site/**', '!assets/**/*.scss' ], + }, + }, + + }); + + // Load plugins + grunt.loadNpmTasks('grunt-contrib-sass'); + grunt.loadNpmTasks('grunt-contrib-uglify'); + grunt.loadNpmTasks('grunt-jekyll'); + grunt.loadNpmTasks('grunt-contrib-connect'); + grunt.loadNpmTasks('grunt-contrib-watch'); + + // Default task(s). + grunt.registerTask('default', [ 'connect', 'watch' ]); + +}; @@ -1,19 +1,77 @@ # Alaveteli documentation (github pages) The `gh-branch` contains the Alaveteli documentation that is hosted -as GitHub Pages, and available at code.alaveteli.org +as GitHub Pages, and available at <http://www.alaveteli.org/docs> -The styling comes from the +The mySociety documentation "github pages" sites share the same styling. +It comes from the [mysociety-docs-theme](https://github.com/mysociety/mysociety-docs-theme) repo, which is included as a submodule in the `theme/` directory. +## Updating the CSS, manually + If you're building locally, and you change the theme, rebuild it with: -`sass --update theme/sass/:assets/css/` + sass --update --style=compressed theme/sass/global.scss:assets/css/global.css + +There's also an Alaveteli-specific stylesheet, so do: + + sass --update --style=compressed assets/sass/alaveteli-org.scss:assets/css/alaveteli-org.css + + +## Viewing locally manually To view the documentation locally using Jekyll, do something like: -`jekyll serve --watch` + `jekyll serve --watch` + + +## Using grunt to work locally + +If you run grunt (there's a Gruntfile in the repo for this branch) then the CSS +will automagically update if you change it, *and* pages magically refresh whenever +you change any of the files. It's like `--watch` on steroids. + +### Installation +In the below you could of course run `sudo gem install` or `npm install -g` but +I personally never think that's a good idea. You must already have gem and git +installed (you probably do). + +``` +gem install --no-document --user-install github-pages +# Add ~/.gem/ruby/2.0.0/bin/ or similar to your $PATH +# Check you can run "jekyll" +git clone --recursive -b gh-pages https://github.com/mysociety/alaveteli alaveteli-pages +cd alaveteli-pages +``` + +If you only want to edit the *text* of the site, this is all you need. Run +`jekyll serve --watch` to run a webserver of the static site, and make changes +to the text you want. + +If you want to edit the CSS or JS, or you'd like live reloading of changes in +your web browser, you might as well set up the thing that monitors it all for +you. You will need npm already installed. + +``` +gem install --no-document --user-install sass +npm install grunt-cli +npm install +node_modules/.bin/grunt +``` + +This will start up a watcher that monitors the files and automatically compiles +SASS, JavaScript, and runs `jekyll build` when necessary. It also live reloads +your web pages. + +Lastly, if you'd like to add more JavaScript *libraries* than the ones already, +you'll additionally need to install bower and use it to fetch the libraries +used: +``` +npm install bower +node_modules/.bin/bower install +``` +Then use bower to install a new library and add it to the `Gruntfile.js`. diff --git a/_config.yml b/_config.yml index 37eefa1f8..ad5c74aeb 100644 --- a/_config.yml +++ b/_config.yml @@ -4,5 +4,6 @@ baseurl: / permalink: pretty markdown: kramdown url: http://code.alaveteli.org +exclude: [ node_modules ] gems: - jekyll-redirect-from diff --git a/package.json b/package.json new file mode 100644 index 000000000..ea5492dfd --- /dev/null +++ b/package.json @@ -0,0 +1,16 @@ +{ + "name": "fixmystreet-documentation", + "description": "Documentation for the FixMyStreet Platform", + "license": "AGPL-3.0", + "version": "1.0.0", + "homepage": "http://fixmystreet.org/", + "scripts": {}, + "devDependencies": { + "grunt": "~0.4.1", + "grunt-contrib-uglify": "~0.2.5", + "grunt-contrib-watch": "~0.6.1", + "grunt-contrib-sass": "~0.7.3", + "grunt-jekyll": "~0.4.1", + "grunt-contrib-connect": "~0.7.1" + } +} |