Skip to content

Commit

Permalink
Built site for gh-pages
Browse files Browse the repository at this point in the history
  • Loading branch information
Quarto GHA Workflow Runner committed Jul 24, 2024
1 parent c137ca7 commit 17f4403
Show file tree
Hide file tree
Showing 17 changed files with 190 additions and 47 deletions.
2 changes: 1 addition & 1 deletion .nojekyll
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
6640b8e8
7dda8a16
143 changes: 143 additions & 0 deletions CONTRIBUTING.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,40 @@
margin: 0 0.8em 0.2em -1em; /* quarto-specific, see https://github.com/quarto-dev/quarto-cli/issues/4556 */
vertical-align: middle;
}
/* CSS for syntax highlighting */
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { display: inline-block; text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
}
pre.numberSource { margin-left: 3em; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
</style>


Expand Down Expand Up @@ -436,6 +470,7 @@ <h2 id="toc-title">On this page</h2>
<li><a href="#new-contributor-guide" id="toc-new-contributor-guide" class="nav-link" data-scroll-target="#new-contributor-guide">New contributor guide</a>
<ul class="collapse">
<li><a href="#quarto-guidance" id="toc-quarto-guidance" class="nav-link" data-scroll-target="#quarto-guidance">Quarto guidance</a></li>
<li><a href="#example" id="toc-example" class="nav-link" data-scroll-target="#example">Example</a></li>
<li><a href="#adding-images-from-draw.io" id="toc-adding-images-from-draw.io" class="nav-link" data-scroll-target="#adding-images-from-draw.io">Adding images from draw.io</a></li>
<li><a href="#issues" id="toc-issues" class="nav-link" data-scroll-target="#issues">Issues</a></li>
<li><a href="#make-changes" id="toc-make-changes" class="nav-link" data-scroll-target="#make-changes">Make Changes</a></li>
Expand Down Expand Up @@ -470,23 +505,131 @@ <h2 class="anchored" data-anchor-id="new-contributor-guide">New contributor guid
<section id="quarto-guidance" class="level3">
<h3 class="anchored" data-anchor-id="quarto-guidance">Quarto guidance</h3>
<p>For more information specific to how a quarto site works, and for examples of what is possible within a static quarto site, see the main <a href="https://quarto.org/" target="_blank">Quarto website</a>.</p>
<p>Hadley Wickham’s book, <a href="https://r4ds.had.co.nz/introduction.html" target="_blank">R for Data Science</a>, gives the following intro to Quarto:</p>
<blockquote class="blockquote">
<p><code>"Quarto is an open-source scientific and technical publishing system. It allows you to create dynamic documents that weave together narrative text, code, and output, such as plots and tables."</code></p>
</blockquote>
<section id="visual-editor" class="level4">
<h4 class="anchored" data-anchor-id="visual-editor">Visual Editor</h4>
<p>The Visual Editor in RStudio offers a WYSIWYM (What You See Is What You Mean) interface for creating Quarto documents. These documents, saved as .qmd files, are written using Markdown—a lightweight syntax for formatting plain text. Specifically, Quarto employs Pandoc Markdown, an enhanced version of Markdown, which supports a variety of elements such as tables, citations, cross-references, footnotes, divs/spans, definition lists, attributes, raw HTML/TeX, and more. Additionally, Quarto allows for the execution of code cells with inline output display. Although Markdown is designed to be straightforward, it still necessitates learning some new syntax.</p>
<p>For those who are new to computational documents like .qmd files but have experience with tools like Google Docs or MS Word, the visual editor in RStudio is the most user-friendly way to begin working with Quarto. In the visual editor, you can use the toolbar buttons to insert images, tables, cross-references, and other elements.</p>
</section>
<section id="adding-images-in-the-right-folder-code-to-do-so" class="level4">
<h4 class="anchored" data-anchor-id="adding-images-in-the-right-folder-code-to-do-so">Adding images (in the right folder, code to do so)</h4>
<p>The visual editor also simplifies inserting images and customizing their display. You can paste an image directly from your clipboard into the visual editor, which will save a copy of the image in your project directory and link to it. Alternatively, you can use the Insert &gt; Figure / Image menu to browse for the image you want to insert or paste its URL. This menu also allows you to resize the image, add captions, alternative text, and links.</p>
<p>The visual editor offers many additional features that become evident as you gain more experience with it.</p>
<p>Most importantly, while the visual editor displays your content with formatting, it saves everything in plain Markdown. You can easily switch between the visual and source editors to view and edit your content in either format.</p>
</section>
<section id="adding-links-within-page-within-site-external-to-site" class="level4">
<h4 class="anchored" data-anchor-id="adding-links-within-page-within-site-external-to-site">Adding links (within page, within site, external to site)]</h4>
<p>In Quarto, you can add links using the following Markdown syntax:</p>
<ol type="1">
<li><p>Inline Links: [Link Text] <code>(https://example.com)</code></p></li>
<li><p>Reference Links: [Link Text][1]</p></li>
</ol>
<p><code>[1]: https://example.com</code></p>
<p>In Quarto, you can also include links within various contexts, such as code blocks or embedded within other content structures, depending on the complexity of your document. However, the basic Markdown link syntax will generally cover most use cases.</p>
<div class="quarto-figure quarto-figure-center">
<figure class="figure">
<p><img src="images/adding_links_example.png" class="img-fluid figure-img" width="300"></p>
<figcaption>Example for adding links</figcaption>
</figure>
</div>
</section>
<section id="adding-videos-other-content" class="level4">
<h4 class="anchored" data-anchor-id="adding-videos-other-content">Adding videos / other content</h4>
<section id="adding-videos" class="level5">
<h5 class="anchored" data-anchor-id="adding-videos"><strong>Adding Videos</strong></h5>
<p>You can embed videos in Quarto documents using HTML, Markdown, or specialised Quarto syntax. Here are some methods:</p>
<ol type="1">
<li>Using a shortcode:</li>
</ol>
<div class="sourceCode" id="cb1" data-shortcodes="false"><pre class="sourceCode markdown code-with-copy"><code class="sourceCode markdown"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>{{&lt; video url &gt;}}</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<ul>
<li>For example, here we embed a YouTube video:</li>
</ul>
<div class="sourceCode" id="cb2" data-shortcodes="false"><pre class="sourceCode markdown code-with-copy"><code class="sourceCode markdown"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>{{&lt; video https://www.youtube.com/embed/wo9vZccmqwc &gt;}} </span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="quarto-video ratio ratio-16x9"><iframe data-external="1" src="https://www.youtube.com/embed/wo9vZccmqwc" title="" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen=""></iframe></div>
<ol start="2" type="1">
<li>Embedding videos in other formats:</li>
</ol>
<ul>
<li>In HTML formats the video will be embedded within the document.</li>
<li>For other formats, a simple link to the video will be rendered.</li>
</ul>
</section>
<section id="adding-other-content" class="level5">
<h5 class="anchored" data-anchor-id="adding-other-content"><strong>Adding Other Content</strong></h5>
<ul>
<li><strong>Audio Files</strong>: You can embed audio files using the HTML <audio> tag.</audio></li>
<li><strong>Interactive Content with HTML Widgets</strong>: Quarto supports various HTML widgets that can add interactive content to your document.</li>
</ul>
</section>
<section id="tips" class="level5">
<h5 class="anchored" data-anchor-id="tips">Tips</h5>
<ul>
<li><strong>Relative Paths</strong>: Use relative paths for local files to ensure your document remains portable.</li>
</ul>
<p>In R, relative paths refer to file or directory paths specified in relation to the current working directory. Relative paths help manage current working files.</p>
<p>If you’re struggling with running your files across different paths in your working directories, then the <a href="https://here.r-lib.org/" target="_blank">here</a> package can sometimes help you solve those types of issues.</p>
<ul>
<li><p><strong>Test Across Browsers</strong>: Ensure multimedia content works across different browsers and devices.</p></li>
<li><p><strong>Output Formats</strong>: Verify that multimedia elements render correctly in the intended output formats (HTML, PDF, etc.).</p></li>
</ul>
<p>By following these methods, you can effectively add videos, images, audio, and interactive content to your Quarto documents, enhancing their informativeness and engagement.</p>
</section>
</section>
<section id="redirecting-pages-where-changing-removing" class="level4">
<h4 class="anchored" data-anchor-id="redirecting-pages-where-changing-removing">Redirecting pages where changing / removing</h4>
<p>Redirecting pages in a Quarto project for R involves creating <code>a _quart.yml</code> configuration file where you can define redirects.</p>
<ol type="1">
<li><p><strong><code>Create/Edit_quarto.yml</code></strong> : Ensure you have a <code>_quarto.yml</code> file in your Quarto project.</p></li>
<li><p><strong><code>Add redirects</code></strong>: In <code>_quarto.yml</code>, define redirects like this: - From: <code>old-page.html</code> to: <code>new-page.html</code></p></li>
<li><p><strong><code>Render Project</code></strong> : Run <code>quarto render</code> in your project directory to apply changes.</p></li>
</ol>
<p>4.<strong><code>Verify</code></strong>: Test old URLs to ensure they redirect correctly.</p>
<p>This sets up URL redirects for pages that have changed or been removed in your Quarto project.</p>
</section>
<section id="checking-for-broken-links-when-changing-headings" class="level4">
<h4 class="anchored" data-anchor-id="checking-for-broken-links-when-changing-headings">Checking for broken links when changing headings</h4>
<p>When changing headings in Quarto project, it’s crucial to ensure that all links referencing these headings are still correct. Here’s a quick guide to check for broken links:</p>
<ol type="1">
<li><p><strong>Change Headings</strong>: Update your headings in the relevant <code>.qmd files</code>.</p></li>
<li><p><strong>Run Quarto’s Built-in Link Checker</strong>: Quarto has a built in feauture to check for broken links.</p></li>
</ol>
<p>Run the following command in your project directory:</p>
<p><code>quarto check</code></p>
<p>This command will scan your project for broken links and report any issues.</p>
<ol start="3" type="1">
<li><p><strong>Manually Update Links</strong>: If any broken links are reported, update them to match the new headings. Use the correct anchors, which typically follow the format <code>#new-heading-text</code>.</p></li>
<li><p><strong>Re-render Project</strong>: After updating links, re-render your project: <code>quarto render</code></p></li>
<li><p><strong>Double-Check</strong>: Manually verify a few pages to ensure that the links work as expected.</p></li>
</ol>
</section>
</section>
<section id="example" class="level3">
<h3 class="anchored" data-anchor-id="example">Example</h3>
<p>If you changed a heading from <code>## Old Heading</code> to <code>## New Heading</code>, make sure all links like <code>[link text](#old-heading)</code> are updated to <code>[link text](#new-heading)</code>. By following these steps, you can efficiently check for and fix broken links when changing headings in your Quarto project.</p>
<section id="building-locally-before-raising-a-pull-request" class="level4">
<h4 class="anchored" data-anchor-id="building-locally-before-raising-a-pull-request">Building locally before raising a pull request</h4>
<p>Here’s a streamlined guide for building your Quarto project locally before raising a pull request (from the terminal):</p>
<ol type="1">
<li><p><strong>Pull Latest Changes</strong>: Make sure your local branch is up-to-date with the main branch. <code>git pull origin main</code></p></li>
<li><p><strong>Make Your Changes</strong>: Edit your <code>.qmd</code> files or other relevant files in the project.</p></li>
<li><p><strong>Build the Project Locally</strong>: Render the entire project to catch any errors. <code>quarto render</code></p></li>
</ol>
<section id="note-while-this-guide-presents-a-terminal-based-workflow-there-are-equivalent-commands-available-in-the-r-console-for-those-who-prefer-working-within-r.-for-example-you-can-use-quarto_preview-in-the-r-console-to-preview-your-quarto-project." class="level6">
<h6 class="anchored" data-anchor-id="note-while-this-guide-presents-a-terminal-based-workflow-there-are-equivalent-commands-available-in-the-r-console-for-those-who-prefer-working-within-r.-for-example-you-can-use-quarto_preview-in-the-r-console-to-preview-your-quarto-project.">Note: While this guide presents a terminal-based workflow, there are equivalent commands available in the R console for those who prefer working within R. For example, you can use <code>quarto_preview()</code> in the R console to preview your Quarto project.</h6>
<ol start="4" type="1">
<li><p><strong>Check for Errors and Warnings</strong>: Review the console output and fix any issues.</p></li>
<li><p><strong>Preview the Project</strong>: Open the generated files in a browser to ensure everything looks correct. <code>quarto preview</code></p></li>
<li><p><strong>Check for Broken Links</strong>: Use Quarto’s link checker to find and fix broken links. <code>quarto check</code></p></li>
<li><p><strong>Commit Your Changes</strong>: Add and commit your changes to your local repository. <code>git add . git commit -m "Describe your changes"</code></p></li>
<li><p><strong>Push Your Changes</strong>: Push your changes to your feature branch. <code>git push origin your-feature-branch</code></p></li>
<li><p><strong>Create a Pull Request</strong>: Go to your repository platform (e.g., GitHub) and create a pull request from your feature branch to the main branch.</p></li>
</ol>
<p>Following these steps ensures your changes are correctly implemented and verified locally, minimising potential issues during the review process.</p>
</section>
</section>
<section id="changing-the-appearance-of-code-blocks" class="level4">
<h4 class="anchored" data-anchor-id="changing-the-appearance-of-code-blocks">Changing the appearance of code blocks</h4>
Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The guidance website is deployed to https://dfe-analytical-services.github.io/an

## How to use

Each page of the site is a single quarto document, with index.qmd as the homepage. When the project is opened locally in RStudio you will be able to preview the website by typing the command `quarto preview` into the terminal.
Each page of the site is a single quarto document, with index.qmd as the homepage. When the project is opened locally in RStudio you will be able to preview the website by typing the command `quarto preview` into the terminal or using `quarto::quarto_preview()` in the R console.

### Tests

Expand Down
Binary file added images/adding_links_example.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">

<meta name="author" content="[email protected]">
<meta name="dcterms.date" content="2024-07-23">
<meta name="dcterms.date" content="2024-07-24">

<title>Analysts’ Guide</title>
<style>
Expand Down Expand Up @@ -465,7 +465,7 @@ <h1 class="title">Analysts’ Guide</h1>
<div>
<div class="quarto-title-meta-heading">Published</div>
<div class="quarto-title-meta-contents">
<p class="date">July 23, 2024</p>
<p class="date">July 24, 2024</p>
</div>
</div>

Expand Down
Loading

0 comments on commit 17f4403

Please sign in to comment.