This project hosts a structure for building out and publishing a map-based scrollytelling interface for the Xetthecum Ecocultural Mapping Project based on R Markdown.
You can browse the published output of this project in these documents:
This was built using R and R Markdown, using free tools such as git, R and R studio, and publish and host it for free using GitHub Pages. These files were distilled from work done for the Maxwell Creek Watershed Project which is being undertaken by Transition Salt Spring.
You can browse the kind of scrollytelling interface which can be produced in the Maxwell Project's GitHub pages. You can browse this own template repository's output at R-Markdown-Background-Reknitted.html.
As a general guide to the potential of storymapping frameworks to use data to tell stories, you can visit two thoroughly elaborated data explorations from the dataARC project which present two stories, "Quantifying an ever-changing landscape" and "Data mining the past" using two mature storymapping frameworks, ESRI/ArcGIS Storymaps and HTML + Binder/Jupyter.
Here we operate a homegrown approach showing how readily available and widely understood open source tools can be orchestrated to produce a basic end-to-end authoring and hosting environment. Consult Knitting Data Communities for some values underlying this work.
If you haven't worked with this kind of project before, you will need the following tools:
-
git for your platform, installed according to instructions like these ones from GitHub.
-
R and R studio, installed from posit's website
In order to reknit the markup rendered by R and R markdown, you will also need the following optional tools:
- node and npm for your platform, installed according to node's instructions.
Rather than doing this yourself, you could enlist a friendly developer to do these actions for you and commit to your repository. Before long, this repository will contain automatic actions to do this using GitHub Actions.
To make your own fork of this repository to start filling it with your own content, follow GitHub's instructions on forking a repository - you will want to choose a new name for the repository as shown in step 4 of these instructions.
For a more simple-minded approach, you can simply copy all the files resulting from cloning this repository into a new
folder on your system (missing out the .git directory).
After this, you can switch to Posit's instructions on using git with R Studio - go to the section named "Creating a new project based on a remote Git or Subversion repository" and supply the repository URL for your forked repository at step 4. If you haven't worked with these tools before, you will want to choose the HTTPS version of the repository URL available from the "Code" dropdown as shown in the following picture:
Another useful guide is at Connect RStudio to Git and GitHub.
If you are going to do your own reknitting, you will now need to download node dependencies for this project by opening a terminal in its root folder and typing
npm install
The first part of the publishing chain is to use the builtin "knitting" functionality in R studio described in the authoring guide - open up the .Rmd file at the roof of the project and click on the small "Knit" button above it. This will produce markup in the "docs" directory. You can commit this to GitHub pages and hence publish it by following the steps in section 12.4 of the guide to using GitHub in R studio.
If this all works fine, you can proceed with editing the document in R-Markdown-Background.Rmd, and building out scripts for further maps in scripts, vector data as SHP flies in spatial_data/vectors and raster data in spatial_data/rasters. Please consult the using Leaflet with R guide for how to add your own map data to your maps.
The sample map contains one simple vector and one simple raster dataset. Each second-level heading in the document -
rendered using ## in markdown, and an <h2> tag in the output markup, will correspond to a separate section in the
scrollytelling interface. Each leaflet map that you render in such a section will be compiled by the reknitting process
into a separate map layer on the shared map. Note that not many R leaflet constructs are currently supported by the
reknitting process - contact us with details of what you
would like to see.
Once your customised map knits properly using the R Studio "Knit" process, you can reknit it by running
npm run build
from the terminal in the project folder. Commit and push the output from this stage using R Studio or git as you prefer.
If you want to reknit to different input or output filenames, edit the reknitJobs block in the configuration file at config.json5. To customise the markup which frames the reknitted output, you can edit the HTML template at src/html/template.html.
To publish the markup resulting from both the knitting and the reknitting process, set up the configuration on your
repository to publish GitHub Pages from the docs folder of the main branch. This is available from the Pages
tab on your repository's settings, as shown in the image below:
You can find our what URL your markup will be published at by looking in the docs directory of your own repository. For example, the docs/R-Markdown-Background-Reknitted.html file is published at https://imerss.github.io/r-scrollytelling-template/R-Markdown-Background-Reknitted.html.
The overall URL of your documents published in GitHub pages will start with https://<your-account>.github.io/<your-repository>.
To suggest improvements to these instructions and publishing system, please raise an issue. For a wider background surrounding this project and its philosophy, please go to Knitting Data Communities.