Quarto (#230)

add dark mode and share button

Author: hturner

.Rbuildignore

@@ -10,33 +10,39 @@ book:
   repo-url: https://github.com/r-devel/rdevguide
   repo-branch: main
   repo-actions: [edit, issue]
+  sharing: [linkedin]
+  open-graph: true
+  image: img/cover_page_scriberia.png
+  downloads: [pdf, epub]
   chapters:
     - index.qmd
-    - introduction.qmd
-    - getting_started.qmd
-    - issue_tracking.qmd
-    - reporting_bugs.qmd
-    - submitting_feature_requests.qmd
-    - reviewing_bugs.qmd                
-    - finding_the_source.qmd             
-    - lifecycle_of_a_patch.qmd
-    - documenting.qmd                    
-    - message_translations.qmd         
-    - testing_pre_release_r_versions.qmd
-    - r_core_developers.qmd
-    - where_to_get_help.qmd              
-    - news_and_announcements.qmd   
-    - developer_tools.qmd             
+    - chapters/introduction.qmd
+    - chapters/getting_started.qmd
+    - chapters/issue_tracking.qmd
+    - chapters/reporting_bugs.qmd
+    - chapters/submitting_feature_requests.qmd
+    - chapters/reviewing_bugs.qmd                
+    - chapters/finding_the_source.qmd             
+    - chapters/lifecycle_of_a_patch.qmd
+    - chapters/documenting.qmd                    
+    - chapters/message_translations.qmd         
+    - chapters/testing_pre_release_r_versions.qmd
+    - chapters/r_core_developers.qmd
+    - chapters/where_to_get_help.qmd              
+    - chapters/news_and_announcements.qmd   
+    - chapters/developer_tools.qmd             
 
 format:
   html:
-    theme: cosmo
-    include-in-header: header.html
+    theme:
+      light: cosmo
+      dark: [cosmo, css/theme-dark.scss]
+    include-in-header: html/header.html
     description-meta: "This guide is a comprehensive resource for contributors (from all levels, beginners, intermediate, and seasoned) to the R project, facilitating their onboarding and helping them navigate the contribution process."
   pdf:
     documentclass: scrreprt
-    include-in-header: preamble.tex
-    include-before-body: frontpage.tex
+    include-in-header: tex/preamble.tex
+    include-before-body: tex/frontpage.tex
   epub:
     cover-image: img/cover_page_scriberia.png
 

_quarto.yml

@@ -48,6 +48,6 @@ Maintainers and contributors are also requested to follow [this guide's code of
 
 This guide is built using Quarto which makes editing it easier, provided you have a GitHub account (sign-up at [github.com](https://github.com/)). After you log-in to GitHub, click on the ‘Edit this page’ (available in the left side column) link highlighted with a red ellipse in the image below. This will take you to an editable version of the the source R Markdown file that generated the page you are on:
 
-![Screenshot of the toolbar in the HTML version of the guide, with the "Edit this page" link highlighted in red.](img/edit_icon.png)
+![Screenshot of the toolbar in the HTML version of the guide, with the "Edit this page" link highlighted in red.](../img/edit_icon.png)
 
 Use the [issue tracker](https://github.com/r-devel/rdevguide/issues) to raise an issue about the guide’s content or to make a feature request.

book.bib

@@ -22,11 +22,11 @@ To get a Bugzilla account send an e-mail to `[email protected]` f
 
 An image of the existing home page of Bugzilla is shared below:
 
-![Screenshot of the existing home page of Bugzilla.](img/bugzilla.png)
+![Screenshot of the existing home page of Bugzilla.](../img/bugzilla.png)
 
 On the home page of Bugzilla, there are various buttons and links. There are four square buttons called as:
 
-![Screenshot of the four square buttons on the home page of Bugzilla.](img/squarebuttons.png)
+![Screenshot of the four square buttons on the home page of Bugzilla.](../img/squarebuttons.png)
 
 1. [File a bug](https://bugs.r-project.org/enter_bug.cgi): You will have to log in to Bugzilla to file a bug using this button
 
@@ -46,18 +46,18 @@ Several useful shortcuts are available from the landing page:
 
 A [quick search](https://bugs.r-project.org/page.cgi?id=quicksearch.html) bar is available on the home page where you can enter a bug number to search or some search terms.
 
-![Screenshot of the quick search bar on the home page of Bugzilla.](img/quicksearch.png)
+![Screenshot of the quick search bar on the home page of Bugzilla.](../img/quicksearch.png)
 
 There is also a section for Common Queries on the home page which includes links to bugs reported and changed in the last 24 hours and last 7 days.
 
-![Screenshot of the Common Queries section on the home page of Bugzilla.](img/commonquery.png)
+![Screenshot of the Common Queries section on the home page of Bugzilla.](../img/commonquery.png)
 
 ## Searching for Bugs to Contribute to {#searching}
 
 When presented with a long list of bugs, it can often be a bit demotivating when it's not clear where to start.
 To help with this, you can use the [**Advanced Search**](https://bugs.r-project.org/query.cgi?format=advanced).
 
-![Screenshot of Advanced Search page showing the following fields: Summary, Product, Component, Status, Resolution](img/bugzilla-adv-search-home.png)
+![Screenshot of Advanced Search page showing the following fields: Summary, Product, Component, Status, Resolution](../img/bugzilla-adv-search-home.png)
 
 This presents several fields that you can use to narrow down your search.
 You can find out what a particular field is by clicking on the header, which will take you to that section in the [**Bug Fields Information Page**](https://bugs.r-project.org/page.cgi?id=fields.html).
@@ -93,19 +93,19 @@ You can use this section to narrow down your search further to filter by things
 
 It can be helpful, for example, to search for bugs labelled with `HELPWANTED`, which indicates bugs that may be suitable for anyone to work on regardless of expertise.
 
-![Screenshot of expanded Detailed Bug Information section showing the following fields: Comment, URL, Keywords (with HELPWANTED entered), Deadline, inclusion/exclusion of bug numbers, Version, Severity, Priority, Hardware, and OS](img/bugzilla-adv-search-detailed-bug-info.png)
+![Screenshot of expanded Detailed Bug Information section showing the following fields: Comment, URL, Keywords (with HELPWANTED entered), Deadline, inclusion/exclusion of bug numbers, Version, Severity, Priority, Hardware, and OS](../img/bugzilla-adv-search-detailed-bug-info.png)
 
 
 ### Search By People {#searching-sbp}
 
 You can use this to narrow down your search to only include results of a specific person or up to three people who have participated in any component of the bug's discusson.
 
-![Screenshot of expanded Search By People section showing three fields allowing you to enter a person's name who can be any of the bug assignee, the reporter, a CC list member, or a commenter](img/bugzilla-adv-search-search-by-people.png)
+![Screenshot of expanded Search By People section showing three fields allowing you to enter a person's name who can be any of the bug assignee, the reporter, a CC list member, or a commenter](../img/bugzilla-adv-search-search-by-people.png)
 
 
 ### Search By Change History {#searching-sbch}
 
 Use this to search for bugs where any of the status fields has been changed (which, depending on the change, could indicate that someone from R-Core has given some attention to the bug).
 This also provides a date range to narrow your search.
 
-![Screenshot of expanded Search by Change History section showing three fields: where ANY of the fields (multi-select list), changed to, and between (dates in YYYY-MM-DD format)](img/bugzilla-adv-search-search-by-change-history.png)
+![Screenshot of expanded Search by Change History section showing three fields: where ANY of the fields (multi-select list), changed to, and between (dates in YYYY-MM-DD format)](../img/bugzilla-adv-search-search-by-change-history.png)

developer_tools.qmd chapters/developer_tools.qmd

@@ -59,32 +59,32 @@ Besides checking in your computer, you can use the Github mirror  [r-devel/r-svn
 
 You should first find the file to edit, via the github interface for example:
 
-![Screenshot of the heading of the src/library/stats/man/Mulinom.Rd](img/rsvn_file_to_edit.png "Opening the file to edit.") 
+![Screenshot of the heading of the src/library/stats/man/Mulinom.Rd](../img/rsvn_file_to_edit.png "Opening the file to edit.") 
 
 Then you can edit it, directly in the interface or using the github interface:
 
-![Screenshot of the file src/library/stats/man/Mulinom.Rd being edited via the Github interface](img/rsvn_edit_file.png "Editing a file via Github interface.")
+![Screenshot of the file src/library/stats/man/Mulinom.Rd being edited via the Github interface](../img/rsvn_edit_file.png "Editing a file via Github interface.")
 
 Create a commit with a message describing the changes
 
-![Screenshot of the commit message](img/rsvn_commit_message.png "Commiting the change in the file.")
+![Screenshot of the commit message](../img/rsvn_commit_message.png "Commiting the change in the file.")
 
 And create a pull request from the branch created to check the changes.
 
-![Screenshot of the message when opening a pull requests from the branch](img/rsvn_commit_pre_PR.png "Starting a pull requests with the changes previously committed.")
+![Screenshot of the message when opening a pull requests from the branch](../img/rsvn_commit_pre_PR.png "Starting a pull requests with the changes previously committed.")
 
 Add a message and description of the svn for other users and the R core to know what is the purpose of this modification:
 
-![Screenshot of the message and content while opening a pull requests for the r-svn repository](img/rsvn_PR_message.png "Describe the changes in the pull request.")
+![Screenshot of the message and content while opening a pull requests for the r-svn repository](../img/rsvn_PR_message.png "Describe the changes in the pull request.")
 
-![Screenshot of the pull requests opened](img/rsvn_PR_created.png "The result of opening a pull requests with the changes.") 
+![Screenshot of the pull requests opened](../img/rsvn_PR_created.png "The result of opening a pull requests with the changes.") 
 
 Once the PR is submitted, some automatic checks will be triggered (they might need to be approved by some other users as per Github rules):
 
-![Screenshot of the checks triggered by opening the pull request](img/rsvn_PR_automatic_checks.png "Automatic checks triggered in the r-devel/r-svn github repository.")
+![Screenshot of the checks triggered by opening the pull request](../img/rsvn_PR_automatic_checks.png "Automatic checks triggered in the r-devel/r-svn github repository.")
 When the checks end you will need to explore the results and asses if the results indicate a problem or not. 
 
-![Screenshot of the results of the Github checks in the r-svn mirror](img/rsvn_checks_results.png "Summary of the results of the automatic checks triggered by opening the pull request.")
+![Screenshot of the results of the Github checks in the r-svn mirror](../img/rsvn_checks_results.png "Summary of the results of the automatic checks triggered by opening the pull request.")
 
 Once you are happy with the changes and the checks report that everything is okay you can retrieve the patch via:
 

documenting.qmd chapters/documenting.qmd

@@ -245,7 +245,7 @@ the Windows Graphical User Interface.
 
 After selecting a component, you can select your preferred language.
 
-![](img/translate_component.png)
+![](../img/translate_component.png)
 
 <!-- **Step 3: Check String Status** -->
 
@@ -257,7 +257,7 @@ After selecting a component, you can select your preferred language.
 
 <!-- given here: https://github.com/r-devel/translations/wiki/Weblate-FAQ -->
 
-<!-- ![](img/unfinished_strings_translate.png) -->
+<!-- ![](../img/unfinished_strings_translate.png) -->
 
 **Step 3: Translate the Message**
 
@@ -266,12 +266,12 @@ Now, you can click on Translate button on your right.
 > Note: More information for String status visit:
 > <https://docs.weblate.org/en/latest/workflows.html#translation-states>
 
-![](img/translate_button.png)
+![](../img/translate_button.png)
 
 Then, start translating the message by typing the translation in the
 text box.
 
-![](img/translate_string_and_save.png)
+![](../img/translate_string_and_save.png)
 
 -   If you are **confident** that the **translation is correct**, make
     sure the "Needs editing" box is **unchecked**.
@@ -294,7 +294,7 @@ text box.
 
 2.  Accept it if you think the automatic suggestion looks good
 
-![](img/auto-suggestion.png)
+![](../img/auto-suggestion.png)
 
 ------------------------------------------------------------------------
 
@@ -326,7 +326,7 @@ Instead of translating one string at a time, it is possible to bulk translate a
 
 2. Select **'Tools > Automatic translation'**
 
-![Tools drop-down menu with "Automatic Translations" selected](img/translate_automatic_translation.png)
+![Tools drop-down menu with "Automatic Translations" selected](../img/translate_automatic_translation.png)
 
 
 3. In the dialog,
@@ -342,7 +342,7 @@ Instead of translating one string at a time, it is possible to bulk translate a
 
 [^09-message-translations-3]: Microsoft Translator is preferred for bulk translation as our free tier covers 2 million characters/month, where DeepL only allows 500k chars/month. If Microsoft Translator translations are much worse than DeepL, it may be useful to use it to translate one string at a time.
 
-![Automatic Translations dialog box](img/translate_dialog.png)
+![Automatic Translations dialog box](../img/translate_dialog.png)
 
 4.  Review the translations, edit as necessary and uncheck **"needing edit"**. 
 

finding_the_source.qmd chapters/finding_the_source.qmd

@@ -10,7 +10,7 @@ We recommend sharing your feature request idea on the [R-devel](https://stat.eth
 
 You can submit a feature request by [filing a bug](https://bugs.r-project.org/enter_bug.cgi) on Bugzilla. Under Component, select "Wishlist", the designated label for feature requests.
 
-![The "Wishlist" component in Bugzilla's bug submission screen.](img/feature-requests.png)
+![The "Wishlist" component in Bugzilla's bug submission screen.](../img/feature-requests.png)
 
 Similar to bugs, you should ensure that the feature request is [not already reported](#already-reported-bugs) and [follow best practices](#good-practices-bugs) whenever possible.
 

getting_started.qmd chapters/getting_started.qmd

@@ -0,0 +1,8 @@
+/*-- scss:defaults --*/
+// Base document colors
+$body-bg: #181818;
+$body-color: white;
+$link-color: #75AADB;
+
+// Code blocks
+$code-block-bg-alpha: -.8;