GithubHelp home page GithubHelp logo

govau / content-guide Goto Github PK

View Code? Open in Web Editor NEW
9.0 20.0 12.0 979 KB

Content Guide

Home Page: https://guides.service.gov.au/content-guide/

License: Creative Commons Attribution 4.0 International

Ruby 10.34% CSS 2.72% Liquid 28.68% HTML 3.56% Dockerfile 0.30% SCSS 54.40%
australian government jekyll guidance writing

content-guide's Introduction

Content Guide

This guide is designed to help people working in the Australian Government create simpler, clearer and faster information.

Live site: https://guides.service.gov.au/content-guide/

Staging site: https://content-guide.apps.y.cld.gov.au/

Test sites: https://content-guide-[test-branchname].apps.y.cld.gov.au/

Visual tests: https://github.com/govau/backstop-content-guide-tests


Test environments (automatic provisioning)


Table of contents

  1. Feedback
  2. Contributing
  3. Developer information
  4. Copyright and license

Feedback

You can leave feedback to the guide in numerous ways:

  1. via the email feedback buttons and links in the guide (Please join our Content Design in Government Google Group to give feedback)
  2. via GitHub issues.

Contributing

ToDo: add useful information here :)

Markdown

To mark-up your content, write in Markdown. We use the 'kramdown' (default) markdown parser, which provides a couple of extra features. For a reference on what's possible see the kramdown quick reference.

Developer information

This guide is built with Jekyll.

Setup

You would only need to do the following if you are a developer. If you are a content editor you can access and editing content for the guide directly via GitHub. However, it can be nice having the guide locally to work and preview --- feel free to ask a developer if you would like to set up a local instance of the guide.

Prep:

git clone github.com:govau/content-guide
cd content-guide
git submodule init
git submodule update

You have two options to instantiate a local environment. Use the Docker option which handles dependency management automatically, or do it yourself.

Option 1: Docker

This option creates a Docker container with all required dependencies and their versions and allows you to keep your host clean. It lets you move between similar projects that require different versions of the same dependencies more easily.

Build the local Docker container:

docker build -t content-guide .

And run it while in the content-guide directory. This will resolve all application dependencies, serve over port 80 and watch over local changes.

docker run --rm --volume="$PWD:/workdir" -p 80:4000 -it content-guide

Point your browser to your docker host, eg http://localhost/content-guide/

Option 2: DIY

  • Ruby
  • Jekyll

We also pull in the 1.x version of the UI-Kit as a submodule.

We will likely change this, and instead package up everything needed to produce a new guide scaffold as a Ruby gem for Jekyll to consume.

Setup locally

gem install bundler
bundle install

Launch locally

bundle exec jekyll serve

If you get gem errors, try

rbenv rehash

If you still have troubles ask for help! (:

Broken link testing

Internal links are tested as part of the CI build pipeline in bin/citest.sh, however to keep test results reproducible external links are skipped.

You should periodically manually test external links with:

bin/checkexternal.sh

Copyright and license

Copyright Digital Transformation Agency. Licensed under the Creative Commons Attribution 4.0 International Public License. See LICENSE file for more details.

About the DTA

The Content Guide is maintained and funded by the Digital Transformation Agency.

content-guide's People

Contributors

aeijdenberg avatar anand-bhat avatar andrewarch avatar danwhitmarsh avatar davidgilbertson avatar davidjb avatar dependabot[bot] avatar dominikwilkowski avatar gazanson avatar gordcorp avatar gregtarry avatar joolswood avatar klepas avatar marksantoso avatar sirleech avatar sukhrajghuman avatar zedzedzed avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

content-guide's Issues

Blockquote rendering

2 issues:

  1. rendering of double quotation marks is potentially confusing for other users to implement and goes against our punctuation guidance. Suggest we remove them entirely.
  2. the change of font is jarring (also harder to read than default font). Suggest changing to body font.

screen shot 2017-02-14 at 1 24 07 pm

Perhaps we can use similar insert text style as GDS?

screen shot 2017-02-14 at 1 26 02 pm

Implement search

2 acceptable short-term solutions (depending on time available):

  1. Implement Google search box.
  2. Implement luna.js search (DTA.gov.au search).

Change example box headings to para text

Auto generation of Example of X (for screen readers) as H3s are semantically wrong when the example appears under existing H3 headings. This happens fairly frequently across site content.

Please generate Example of X as para text instead.

Using & in longer headings

Nigel suggests:

"I feel we need to explain that you don't use & in headings etc when it's part of a longer phrase.

Eg: Caring for family members and loved ones"

Related to: ampersands.md

Graphic for header

We should use something different from the DTA Design Guide graphic to help users understand they are at a different guide.
Uploading Screen Shot 2017-02-14 at 2.59.12 pm.png…

Create updates page (changelog)

  • Write changelog.md file.
  • Update links to live pages (blocked until rest of content proofing is finished).
  • Proof changelog.

Home page design

I've got as far as I can with the home page (I've merged from into develop) --- need help to get unblocked:

  • Agree on template
  • Make CTAs work with H2s (or revert to plain H3s)
  • Either:
  • design page.liquid layout and turn /sources/ and /how-to-use-guide/ into pages not collections
  • be able to link to the current collections without having them appear as cards on the home page (rendering of the HTML is dependent on inclusion in the _config.yml).
  • Re-configure homepage.liquid so it pulls content from md files rather than a horrible combination of index.md and from within homepage.liquid itself (ideally we would pull content from an intro.md followed by the cards and then content from bottom.md (or the like)).
  • Make sure home page content spans the full page rather than wrapping at the mobile breakpoint. See:
    screen shot 2017-03-16 at 3 36 05 pm
  • Tweak white spacing generally.
  • Deletefeature/11-homepage-nav-layout and other distracting branches.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.