diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bec1d2f..8204d5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,18 +21,160 @@ To get an overview of the project, read the [README](README.md). Here are some r 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 [Quarto website](https://quarto.org/). +Hadley Wickham's book, [R for Data Science](https://r4ds.had.co.nz/introduction.html), gives the following intro to Quarto: + +> `"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."` + +#### Visual Editor + +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. + +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. + #### Adding images (in the right folder, code to do so) +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 > 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. + +The visual editor offers many additional features that become evident as you gain more experience with it. + +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. + #### Adding links (within page, within site, external to site)\] +In Quarto, you can add links using the following Markdown syntax: + + 1. Inline Links: + [Link Text] ``(https://example.com)`` + + 2. Reference Links: + [Link Text][1] + + `` [1]: https://example.com`` + +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. + + ![Example for adding links](images/adding_links_example.png){width=300} + #### Adding videos / other content +##### **Adding Videos** +You can embed videos in Quarto documents using HTML, Markdown, or specialised Quarto syntax. Here are some methods: + +1. Using a shortcode: +``` {.markdown shortcodes="false"} +{{< video url >}} +``` + - For example, here we embed a YouTube video: + +``` {.markdown shortcodes="false"} +{{< video https://www.youtube.com/embed/wo9vZccmqwc >}} +``` +{{< video https://www.youtube.com/embed/wo9vZccmqwc >}} + +2. Embedding videos in other formats: + - In HTML formats the video will be embedded within the document. + - For other formats, a simple link to the video will be rendered. + +##### **Adding Other Content** + - **Audio Files**: + You can embed audio files using the HTML