initial commit hg

.github/ISSUE_TEMPLATE/standard-issue-template.md

@@ -0,0 +1,18 @@
+---
+name: Standard issue template
+about: For requesting changes or new features
+title: 'Issue report template (Replace with a description of your issue)'
+labels: ''
+assignees: ''
+
+---
+
+## What type of issue is this?
+
+- [ ] Suggesting a change to a published page
+- [ ] Requesting something new
+- [ ] Other
+
+## Details
+
+Replace this text with a description of what you are suggesting or asking for.

.gitignore

@@ -0,0 +1,11 @@
+# R files
+*.Rhistory
+*.RData
+*.rData
+*.Ruserdata
+*.Rcheck
+*.Rproj.user
+
+# Local testing environment files
+Gemfile.lock
+docs/_site/

CONTRIBUTING.md

@@ -0,0 +1,184 @@
+## Contributing instructions
+
+We welcome contributions to our guidance or other resources. If you would like to suggest a change, please either [raise an issue](https://github.com/ukhsa-collaboration/statistics-production-hub/issues), [email us](mailto:ukhsa_hopstats@ukhsa.gov.uk) or raise a pull request. 
+
+The sections below describe the setup of this repository and how to reproduce some of the markdown features used within the guidance pages. 
+
+
+### Interacting with this repository
+
+#### Cloning the repository
+
+In a new folder, using GitBash (or equivalent), run the following code:
+
+```
+git clone https://github.com/ukhsa-collaboration/statistics-production-hub
+```
+
+Open the .Rproj file to interact with the contents. You should not need to set any remotes for push/pull operations.
+
+Remember to run `git pull` regularly to keep up to date with the main branch. 
+
+#### Branching
+
+The 'main' branch is protected, meaning you will have to create a new branch to make any changes. 
+
+To do this, on your local machine, first update your 'main' branch using `git pull`. Then run `git checkout -b branch-name` to create and switch to a new branch. You can switch between branches (for example, to work on different fixes) by using `git checkout branch-name`. 
+
+Branch names should be short but descriptive, with each word separated by a hyphen. Author initials should be added to the prefix. For example: `"bc-update-data-vis"`.
+
+Use `git add` and `git commit -m "a clear descriptive commit message"` as usual to stage and commit your changes. 
+
+Once you have finished making your changes, push your branch to GitHub (using `git push` - it may give you instructions for setting an upstream branch). Then log in to GitHub and raise a pull request to have your changes reviewed and merged into 'main'. 
+
+
+## Building websites with Jekyll and GitHub
+
+[See a useful resource for working with Jekyll in GitHub here](https://carpentries-incubator.github.io/jekyll-pages-novice/). 
+
+### Folder and file structure
+The root folder can be used to store any non-website content. 
+
+Anything contained within `docs` is used to render the live site (this can be changed if needed via GitHub > Settings > Pages). 
+
+Individual pages should be contained within the `docs` folder (not in sub-folders), and in .md format. 
+
+The `_includes` folder is used to store .html/.js snippets to be inserted into other files via Liquid commands (for example, `{% include site-nav.html %}`).
+
+The `_layouts` folder is used to store larger template files. 
+
+The `assets` folder is used to store .css stylesheets and images. 
+
+The `_config.yml` file can be used to store sitewide values. These are then inserted to other pages via Liquid commands (for example, `{{ site.email }}`). 
+
+### Creating direct download links for files
+Direct download links are used for files such as the QA review conversation tool. 
+
+To get a link:
+1. Navigate to the file in the assets/downloads folder in GitHub (click on the actual file).
+2. Right-click "Raw", and "Copy link address".
+3. Paste that URL into your markdown file, formatting as with any other link. 
+
+### Markdown commands used in this site
+Most of what goes into the .md files will be standard markdown. Some other code is custom built for this site, relying on scripts found within the `_includes` folder.
+
+The features used within this site can be replicated as follows.
+
+#### Block quotes
+
+Add an arrow (">") to the start of each line. You can use other markdown tags (headers, bullets) within this. 
+
+```
+> ## Main messages
+>
+> - Message 1
+> - Message 2
+> - Message 3
+```
+
+#### Expandable sections
+
+First include the hidden content within a 'capture' block like below. 
+
+Make sure to add a unique number to the end of each block title. Numbers should be unique across all expandable blocks in the whole document. 
+
+```
+{% capture expandable_content_1 %}
+Content goes here, written in normal markdown.
+{% endcapture %}
+
+{% capture expandable_content_2 %}
+This is a second expandable section.
+{% endcapture %}
+```
+
+Then you can use the following code to include expandable sections with the appropriate titles. 
+
+The 'block-start' and 'block-end' lines are needed for styling. 
+
+The parameter given in 'content' should match the title of the relevant capture block declared above. 
+
+Be careful to use a unique number in each line (numbers should also be unique within the entire markdown file). The title will display within the button used to expand the section. 
+
+```
+{% include expandable-block-start.html %}
+  {% include expandable-section.html number="1" content=expandable_content_1 title="This is the first title" %}
+  {% include expandable-section.html number="2"  content=expandable_content_2 title="This is the second title" %}
+{% include expandable-block-end.html %}
+
+```
+
+
+#### Code blocks
+````
+```
+Code block
+line 2
+line 3
+```
+````
+
+
+#### Images
+
+To add images to a page, first add the file to the `docs/assets/img/` folder.
+
+Then link using the following code, adding the correct filepath and alt-text:
+
+`<img src="assets/img/laptophands.jpg" alt="A picture of a person working at a laptop">`
+
+
+##### Image and text side-by-side
+If you want to have an image next to some text, you can do that using the code below. 
+
+Note that you should specify the image width and height. 
+
+
+```
+<div class="image-text-container">
+    <img src="assets/img/image.png" width="460px" height="318px" alt="provide some alternative text here">
+    <p>The text goes here</p>
+</div>
+```
+
+#### Title+content cards (like the ones found in the QA guidance)
+
+First include the card content within a 'capture' block like below. 
+
+Make sure to add a unique number to the end of each block title. Numbers should be unique across all cards in the whole document. 
+
+```
+{% capture card_content_1 %}
+Content goes here, written in normal markdown.
+{% endcapture %}
+
+{% capture card_content_2 %}
+This is content for a second card.
+{% endcapture %}
+```
+
+Then you can use the following code to include cards with the appropriate titles. 
+
+The 'container-start' and 'container-end' lines are needed for styling. 
+
+The parameter given in 'content' should match the title of the relevant capture block declared above. 
+
+```
+{% include cards-container-start.html %}
+  {% include card.html content=card_content_1 title="This is the first title" %}
+  {% include card.html content=card_content_2 title="This is the second title" %}
+{% include cards-container-end.html %}
+
+```
+
+
+### Setting up a local testing environment
+Unless you set up a local testing environment, the only way to see what your changes will look like is to push them to main and have GitHub rebuild the live site. This obviously comes with inherent risks. 
+
+[Follow this guide](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll).
+
+First, you will need to install Ruby. Then run `gem install bundler` to install the bundler gem. Getting this to work around permission restrictions can be difficult. You should get in touch with your IT department to support with this, and ChatGPT can also be your friend in understanding how to get around certain error messages! 
+
+Once you have managed to install Ruby and the Bundler gem, you should create a Gemfile and add it to your project (you can copy the example in the root of this project). Then run `bundler install` in your terminal. Make sure to run `bundler update github-pages` on a semi-regular basis, otherwise your local testing environment might look different to the published version.
+
+To create the locally hosted site, navigate to the 'docs' folder in GitBash (for example, using `cd docs`), then run the following command: `bundler exec jekyll serve`. This will give a server address; navigate there to see your site.  

Gemfile

@@ -0,0 +1,6 @@
+# Ruby Gemfile used for creating a local testing environment
+# See our [contributing instructions](https://github.com/ukhsa-collaboration/statistics-production-hub/blob/main/CONTRIBUTING.md) page for more guidance
+
+source 'https://rubygems.org'
+
+gem 'github-pages', group: :jekyll_plugins

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 UK Health Security Agency (UKHSA)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,6 +1,9 @@
-# UKHSA Statistics Production Hub
-This repository is being created by the Statistics Production Division in the UK Health Security Agency (UKHSA). 
+## UKHSA Statistics Production Hub
 
-It will be used to host a number of guidance materials and other resources relating to the production and dissemination of statistics.
+This repository has been created by the Statistics Production Division in the UK Health Security Agency (UKHSA). It is used to host a number of guidance materials and other resources relating to the production and dissemination of statistics. 
 
-Watch this space for updates! 
+We have decided to open source these materials to better enable sharing across government (and beyond), and to invite others to share their insights with us. 
+
+If you would like to contribute to this repository or make suggestions for additions or improvement, please see our [contributing instructions](/CONTRIBUTING.md).
+
+Contact: <UKHSA_HOPSTATS@ukhsa.gov.uk>

docs/_config.yml

@@ -0,0 +1,3 @@
+description: "This site contains guidance materials produced by the Statistics Production Division of UKHSA."
+email: "UKHSA_HOPSTATS@ukhsa.gov.uk"
+github: "https://github.com/ukhsa-collaboration/statistics-production-hub"

docs/_includes/card.html

@@ -0,0 +1,4 @@
+<div class="card" {% if include.id %}id="{{ include.id }}"{% endif %}>
+  <div class="card-top"><h4>{{ include.title }}</h4></div>
+  <div class="card-bottom"><p>{{ include.content | markdownify }}</p></div>
+</div>

docs/_includes/cards-container-end.html

@@ -0,0 +1 @@
+</div>

docs/_includes/cards-container-start.html

@@ -0,0 +1 @@
+<div class="cards-container">

docs/_includes/expandable-block-end.html

@@ -0,0 +1 @@
+</div>

docs/_includes/expandable-block-start.html

@@ -0,0 +1 @@
+<div class="expandables-block">

docs/_includes/expandable-section.html

@@ -0,0 +1,7 @@
+<button type="button" id="expanded-header-{{ include.number }}" aria-controls="expanded-content-{{ include.number }}" aria-expanded="false" class="expandable-header">
+  <h5>{{ include.title }}</h5>
+</button>
+
+<div id="expanded-content-{{ include.number }}" class="expandable-contents" aria-hidden="true">
+  {{ include.content | markdownify }}
+</div>

docs/_includes/expandable-sections.js

@@ -0,0 +1,14 @@
+const expandables = document.getElementsByClassName("expandable-header");
+
+const expand = function(){
+  target = this.getAttribute('aria-controls');
+  expanded = this.getAttribute('aria-expanded');
+
+  if(expanded == "true"){
+    document.getElementById(target).setAttribute("aria-hidden", true);
+    this.setAttribute("aria-expanded", false);
+  } else if(expanded == "false"){
+    document.getElementById(target).setAttribute("aria-hidden", false);
+    this.setAttribute("aria-expanded", true);
+  }
+}

docs/_includes/footer.html

@@ -0,0 +1,19 @@
+<div id="little-banner" style="margin-top: 35px"></div>
+
+<div id="footer">
+
+  <div id="footer-container">
+
+    <p>Users are encouraged to apply the guidance on this site in a way that is appropriate for their teams and circumstances</p>
+
+    <p style="margin-bottom: 0;">If you have any feedback or suggestions for this site, please <a href="mailto:UKHSA_HOPSTATS@ukhsa.gov.uk?subject=Statistics Production Hub">email us</a> or <a href="https://github.com/ukhsa-collaboration/statistics-production-hub/blob/main/CONTRIBUTING.md">see our contributing instructions on GitHub</a></p>
+
+    <div id="copyright-block">
+      <p><svg aria-hidden="true" focusable="false" class="govuk-footer__licence-logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 483.2 195.7" height="17" width="41"><path fill="currentColor" d="M421.5 142.8V.1l-50.7 32.3v161.1h112.4v-50.7zm-122.3-9.6A47.12 47.12 0 0 1 221 97.8c0-26 21.1-47.1 47.1-47.1 16.7 0 31.4 8.7 39.7 21.8l42.7-27.2A97.63 97.63 0 0 0 268.1 0c-36.5 0-68.3 20.1-85.1 49.7A98 98 0 0 0 97.8 0C43.9 0 0 43.9 0 97.8s43.9 97.8 97.8 97.8c36.5 0 68.3-20.1 85.1-49.7a97.76 97.76 0 0 0 149.6 25.4l19.4 22.2h3v-87.8h-80l24.3 27.5zM97.8 145c-26 0-47.1-21.1-47.1-47.1s21.1-47.1 47.1-47.1 47.2 21 47.2 47S123.8 145 97.8 145"></path></svg> All content is available under the <a href="https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/">Open Government Licence v3.0</a>, except where otherwise stated</p>
+
+      <p id="copyright-notice">&copy; {{ "now" | date: "%Y" }} Crown Copyright</p>
+    </div>
+
+  </div>
+
+</div>

docs/_includes/site-nav.html

@@ -0,0 +1,21 @@
+<div id="site-nav">
+    <a href="/statistics-production-hub/" style="display:inline-block;"><p>Go back to see other topics</p></a>
+
+    {% if page.page-group-title %}
+    <p style="margin: 12px 10px 12px 0px; border-left: 1pt solid #ada8a8; display:inline-block;">&nbsp;</p>
+    <p style="font-weight:bold">{{ page.page-group-title}} pages:</p>
+    {% endif %}
+
+    {% if page.page1 %}
+    <a href="{{ page.page1.url }}"><p>{{ page.page1.name }}</p></a>
+    {% endif %}
+
+    {% if page.page2 %}
+      <a href="{{ page.page2.url }}"><p>{{ page.page2.name }}</p></a>
+    {% endif %}
+
+    {% if page.page3 %}
+      <a href="{{ page.page3.url }}"><p>{{ page.page3.name }}</p></a>
+    {% endif %}
+
+</div>

docs/_includes/sources-text.md

@@ -0,0 +1 @@
+This page is based upon a range of sources from across government and beyond. For a reading list, please see the [sources](#sources) section towards the bottom of this page.