Update guide to use scoped component previews (and other fixes)

.gitignore

@@ -5,13 +5,15 @@ doc/*
 *.gem
 *.yardoc
 coverage/*
+crash.log
 
 guide/tmp
 guide/output
 guide/*.log
 guide/node_modules
+guide/content/assets/fonts
 guide/content/assets/images
-guide/content/javascripts/*.js
-guide/content/javascripts/*.map
-
-crash.log
+guide/content/assets/rebrand
+guide/content/assets/manifest.json
+guide/content/javascripts/*.min.js
+guide/content/javascripts/*.min.js.map

Gemfile

@@ -7,5 +7,6 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 gemspec
 
 group 'nanoc' do
+  gem 'govuk_markdown'
   gem 'nanoc-live'
 end

guide/Rules

@@ -12,14 +12,21 @@ compile '/**/*.slim' do
   write item.identifier.without_ext + '/index.html'
 end
 
+compile '/**/*.md' do
+  filter :govuk_markdown
+  filter :colorize_syntax, default_colorizer: :rouge
+  layout '/default.*'
+  write item.identifier.without_ext + '/index.html'
+end
+
 ignore '/**/_*.scss'
 compile '/**/*.scss' do
   filter :dart_sass,
-    targets: %w(content/stylesheets/application.scss),
-    load_paths: %w(
-      node_modules/govuk-frontend/
-      node_modules/@x-govuk/govuk-prototype-components/
-    )
+    load_paths: %w(.),
+    pkg_importer: 'node',
+    quiet_deps: true,
+    silence_deprecation: 'import',
+    style: 'compressed'
   write item.identifier.without_ext + '.css'
 end
 

guide/content/building-blocks/fieldsets.slim

@@ -2,20 +2,20 @@
 title: Fieldsets
 ---
 
-p.govuk-body
-  | Fieldsets are used to group related form elements. They are added
-    automatically by the radio button, checkbox and date helpers but can be
-    manually applied to other groups where applicable.
+markdown:
+  Fieldsets are used to group related form elements. They are added
+  automatically by the radio button, checkbox and date helpers but can be
+  manually applied to other groups where applicable.
 
 == render('/partials/example.*',
   caption: 'A fieldset for capturing an address',
   code: address_fieldset) do
 
-  p.govuk-body
-    | A common use case for fieldsets is grouping address fields. The
-      individual components of an address don’t really make sense alone so
-      grouping them is a logical step. The grouping also improves the experience
-      for screen reader users, the screen reader will announce the legend
-      before reading the individual field labels.
+  markdown:
+    A common use case for fieldsets is grouping address fields. The
+    individual components of an address don’t really make sense alone so
+    grouping them is a logical step. The grouping also improves the experience
+    for screen reader users, the screen reader will announce the legend
+    before reading the individual field labels.
 
 == render('/partials/related-navigation.*', links: fieldset_info)

guide/content/building-blocks/injecting-content.slim

@@ -2,54 +2,41 @@
 title: Injecting content
 ---
 
-p.govuk-body
-  | Sometimes a label, legend and hint don’t give enough of an explanation as
-    to why a question is being asked or what the consequences of answering it
-    might be. In these cases, the form builder supports the injection of HTML
-    into most helpers. This content is inserted after the hint and before the
-    form control.
+markdown:
+  Sometimes a label, legend and hint don’t give enough of an explanation as
+  to why a question is being asked or what the consequences of answering it
+  might be. In these cases, the form builder supports the injection of HTML
+  into most helpers. This content is inserted after the hint and before the
+  form control.
 
-p.govuk-inset-text
-  | Injected content is automatically associated with the element via its
-    <code>aria-describedby</code> attribute allowing assistive technologies to
-    provide the user with a full explanation of what is required.
+.govuk-inset-text
+  markdown:
+    Injected content is automatically associated with the element via its
+    `aria-describedby` attribute allowing assistive technologies to provide the
+    user with a full explanation of what is required.
 
-p.govuk-body
-  | The following helpers support content injection:
+markdown:
+  The following helpers support content injection:
 
-ul.govuk-list.govuk-list--bullet
-  li
-    code #govuk_collection_check_boxes
-  li
-    code #govuk_collection_radio_buttons
-  li
-    code #govuk_collection_select
-  li
-    code #govuk_date_field
-  li
-    code #govuk_email_field
-  li
-    code #govuk_error_summary
-  li
-    code #govuk_file_field
-  li
-    code #govuk_number_field
-  li
-    code #govuk_password_field
-  li
-    code #govuk_phone_field
-  li
-    code #govuk_text_area
-  li
-    code #govuk_text_field
-  li
-    code #govuk_url_field
+  * `#govuk_collection_check_boxes`
+  * `#govuk_collection_radio_buttons`
+  * `#govuk_collection_select`
+  * `#govuk_date_field`
+  * `#govuk_email_field`
+  * `#govuk_error_summary`
+  * `#govuk_file_field`
+  * `#govuk_number_field`
+  * `#govuk_password_field`
+  * `#govuk_phone_field`
+  * `#govuk_text_area`
+  * `#govuk_text_field`
+  * `#govuk_url_field`
 
 == render('/partials/example.*',
   caption: 'A radio button collection with a custom warning',
   code: text_area_with_injected_content,
   sample_data: departments_data_raw) do
 
-  p.govuk-body
-    | All content supplied via a block is considered supplementary to the label
-      and hint.
+  markdown:
+    All content supplied via a block is considered supplementary to the label
+    and hint.

guide/content/building-blocks/localisation.slim

@@ -2,100 +2,93 @@
 title: Localisation
 ---
 
-p.govuk-body
-  | The simplest way of adding textual information like labels and hints to
-    forms is to provide strings as arguments to the form helpers.
-
-pre.app-code--block
-  code.highlight.language-ruby
-    | = f.govuk_text_field :name, label: { text: 'Your full name' }
-
-p.govuk-body
-  | On larger, more-complex projects, copy is spread throughout the application
-    and often duplicated, making it difficult for content designers to make
-    changes.
-
-p.govuk-body
-  | Many teams approach this problem by making use of
-    #{link_to('Rails’ excellent localisation functionality', rails_localisation_link).html_safe},
-    allowing text to be stored in locale dictionaries. This allows editors to
-    make changes without the risk of breaking templates and having to learn
-    templating languages and hunt down content.
-
-p.govuk-body
-  | You can use HTML in locales if you append the suffix <code>_html</code> to
-    the key.
+markdown:
+  The simplest way of adding textual information like labels and hints to
+  forms is to provide strings as arguments to the form helpers.
+
+  ```language-ruby
+  = f.govuk_text_field :name, label: { text: 'Your full name' }
+  ```
+
+  On larger, more-complex projects, copy is spread throughout the application
+  and often duplicated, making it difficult for content designers to make
+  changes.
+
+  Many teams approach this problem by making use of
+  #{link_to('Rails’ excellent localisation functionality', rails_localisation_link).html_safe},
+  allowing text to be stored in locale dictionaries. This allows editors to
+  make changes without the risk of breaking templates and having to learn
+  templating languages and hunt down content.
+
+  You can use HTML in locales if you append the suffix `_html` to the key.
 
 == render('/partials/example.*',
   caption: 'Populating label, caption and hint text from the localisation data',
   localisation: favourite_kind_of_hat_locale,
   code: favourite_kind_of_hat) do
 
-  p.govuk-body
-    | Note that despite the <code>text</code> attribute being omitted from
-      the label options hash, the other display and formatting parameters
-      can be supplied and work in the normal manner.
-
-p.govuk-body
-  | Radio and check box labels use a special key in the locale dictionary
-    composed from the attribute name and the suffix <code>_options</code>. This
-    makes it possible to localise the fieldset legend and each of the
-    individual choices separately.
-
-  == render('/partials/example.*',
-    caption: 'Populating radio labels from the localisation data',
-    localisation: contact_type_locale,
-    code: contact_type,
-    sample_data: contact_types_data_raw)
-
-  == render('/partials/example.*',
-    caption: 'Populating check box labels from the localisation data',
-    localisation: department_check_boxes_locale,
-    code: department_check_boxes,
-    sample_data: departments_value_data_raw)
-
-  == render('/partials/example.*',
-    caption: 'A more comprehensive example of localised check boxes',
-    localisation: movie_genre_check_boxes_locale,
-    code: movie_genre_check_boxes) do
-    == render('/partials/fieldset-warning.*', input_type: 'checkbox')
-
-  == render('/partials/example.*',
-    caption: 'Customising locale structure',
-    localisation: custom_locale,
-    code: role_name,
-    custom_config: custom_locale_config,
-    raw_config: custom_locale_config_raw) do
-
-    p.govuk-body
-      | There are many approaches to organising localisation data and while the
-        default will work for most projects, sometimes a different approach can
-        be beneficial. This is especially true when working with external
-        localisation agencies or when dealing with large volumes of copy.
-
-    p.govuk-body
-      | To customise the location of our localisation strings, we can
-        #{link_to('configure', '/introduction/configuration').html_safe} the schema as part of the application’s initialisation process.
-
-    h4.govuk-heading-s Contexts
-
-    p.govuk-body
-      | There are four contexts supported by the form builder: <em>label</em>,
-        <em>legend</em>, <em>caption</em> and <em>hint</em>. Custom locale
-        schemas are configured using an array of symbols that match your locale
-        structure.
-
-    p.govuk-body
-      | The special value <code>__context__</code> is used to represent the
-        current translation context. It will automatically be replaced with
-        either <em>label</em>, <em>legend</em>, <em>caption</em> or <em>hint</em> when the translation key is generated.
-
-    p.govuk-body
-      | When retrieving a localised string the builder first checks whether
-        a contextual schema has been set for the context. If there hasn’t,
-        the <code>localisation_schema_fallback</code> key will be used. <strong>It is the only schema set by default</strong>.
-
-    .govuk-inset-text
-      p.govuk-body
-        | Captions are rendered inside the corresponding <code>label</code> or
-          <code>legend</code> tag. If the label or legend is hidden or not rendered, the caption won’t be either.
+  markdown:
+    Note that despite the `text` attribute being omitted from the label options
+    hash, the other display and formatting parameters can be supplied and work
+    in the normal manner.
+
+markdown:
+  Radio and check box labels use a special key in the locale dictionary
+  composed from the attribute name and the suffix `_options`. This makes it
+  possible to localise the fieldset legend and each of the individual choices
+  separately.
+
+== render('/partials/example.*',
+  caption: 'Populating radio labels from the localisation data',
+  localisation: contact_type_locale,
+  code: contact_type,
+  sample_data: contact_types_data_raw)
+
+== render('/partials/example.*',
+  caption: 'Populating check box labels from the localisation data',
+  localisation: department_check_boxes_locale,
+  code: department_check_boxes,
+  sample_data: departments_value_data_raw)
+
+== render('/partials/example.*',
+  caption: 'A more comprehensive example of localised check boxes',
+  localisation: movie_genre_check_boxes_locale,
+  code: movie_genre_check_boxes) do
+  == render('/partials/fieldset-warning.*', input_type: 'checkbox')
+
+== render('/partials/example.*',
+  caption: 'Customising locale structure',
+  localisation: custom_locale,
+  code: role_name,
+  custom_config: custom_locale_config,
+  raw_config: custom_locale_config_raw) do
+
+  markdown:
+    There are many approaches to organising localisation data and while the
+    default will work for most projects, sometimes a different approach can
+    be beneficial. This is especially true when working with external
+    localisation agencies or when dealing with large volumes of copy.
+
+    To customise the location of our localisation strings, we can
+    #{link_to('configure', '/introduction/configuration').html_safe} the schema as part of the application’s initialisation process.
+
+    ### Contexts
+
+    There are four contexts supported by the form builder: _label_, _legend_,
+    _caption_ and _hint_. Custom locale schemas are configured using an array
+    of symbols that match your locale structure.
+
+    The special value `__context__` is used to represent the current
+    translation context. It will automatically be replaced with either _label_,
+    _legend_, _caption_ or _hint_ when the translation key is generated.
+
+    When retrieving a localised string the builder first checks whether
+    a contextual schema has been set for the context. If there hasn’t,
+    the `localisation_schema_fallback` key will be used. **It is the only
+    schema set by default**.
+
+  .govuk-inset-text
+    markdown:
+      Captions are rendered inside the corresponding `label` or `legend` tag.
+      If the label or legend is hidden or not rendered, the caption won’t be
+      either.