Setting things up

DARIAH-CAMPUS learning resources are

  • written in Markdown, a lightweight markup language with easy-to-learn, plain-text formatting syntax; and
  • hosted on GitHub, a popular repository hosting service based on the open-source version control software called git.

To develop content for DARIAH-CAMPUS, you should:

  • use a text editor that supports Markdown. If you don’t already use one, we recommend Atom.
  • be familiar with our GitHub submission and editing workflow.

In this chapter, we’ll help you:

  • set up Atom as your text editor
  • get a copy of DARIAH-Campus on your computer so that you can work on your contribution locally
  • show you how to run DARIAH-Campus on your computer so that you can preview your contribution to see exactly what it would look like once it’s published on DARIAH-Campus.

Setting up Atom

If you don’t already use a Markdown-enabled text editor but wish to create content for DARIAH-CAMPUS, you may want to use Atom, a customizable, cross-platform open-source text editor.

If you already use a Markdown-enabled editor, you should continue to do so. We’re providing the instructions how to set up Atom only for those who are new to Markdown. You should stick to the tools you know (and hopefully like).

  1. Download and install Atom.
  2. Open Atom.
  3. Go to Atom > Preferences (if you are on a Mac) or File > Settings (if you are on Windows). Then click on Install: atom settings
  4. Make sure the “Packages” tab next to the search field is selected. Then type “mdxjs” in the search field and wait for results to show up. You should see a package called language-mdxjs in the results. Click on install. atom install mdxjs
  5. In the search field, type: “Markdown Preview Enhanced”. Install markdown-preview-enhanced.
  6. Once the install finishes, click on Settings: atom markdown preview settings
  7. Once you open the settings for Markdown Preview Enhanced, you should see something like this: atom markdown preview settings2
  8. Click on the File Extension input field in Settings and type , .mdx after .markdown like this: atom markdown preview settings3
  9. Uncheck the check box next to “Break On Single New Line”: atom markdown preview settings4 You don’t need to hit save.
  10. Finally, go back to “Install”, search for and install “Toolbar Markdown Writer”.
  11. Atom will ask you if you want to install dependencies, click on “Yes”: atom markdown toolbar and dependencies

You should now have a functioning environment in Atom for your work on new DARIAH-CAMPUS learning resources.

Setting up DARIAH-Campus locally

  1. If you haven’t used GitHub before, make sure you sign up for a free account before you proceed.
  2. Make sure you’re logged in on GitHub.com.
  3. Download and install GitHub Desktop on your computer.
  4. Open GitHub Desktop on your computer.
  5. Authenticate your GitHub Desktop application with your GitHub credentials by following these instructions.
  6. In your browser, go to https://github.com/DARIAH-ERIC/dariah-campus and click on “fork”. github fork
  7. If you are a contributor to various organizational repositories, GitHub may ask you to select where you would like to fork dariah-campus. Make your choice. github fork to which repo
  8. Once the forking finishes, you will be taken to your own personal fork of DARIAH-CAMPUS. To make sure you are in the fork, check out that your user name (or the name of the organizational repository youo selected in step 7 above) is displayed in the upper left corner. github fork check your name
  9. Click on “Clone or download”, then select “Open in Desktop”. github clone and open in desktop
  10. In GitHub Desktop, choose where you want to save the cloned DARIAH-CAMPUS fork on your computer. github desktop saving a fork
  11. The first you do this, it may take a couple of minutes, but don’t despair, things will be quicker after the initial clone. Once you finish cloning your fork, you should see something like this: github desktop result of cloned fork
  12. To get to the folder with DARIAH-CAMPUS on your computer, click on Open in Atom (or your preferred editor, if you already set it up).

Previewing DARIAH-Campus locally

Step 1 - installing all necessary apps/programs

Step 1a) Installing ‘Homebrew’

  • Open up Terminal (usually found in ‘Utilities’ on a Mac).
  • Go to https://brew.sh/
  • Select the ‘Install Homebrew’ link and paste it into Terminal
  • You will be prompted for a password in Terminal: enter your laptop password. The installation will begin.

Step 1b) Installing Node.js

To do this,

  • type: ”brew install node” into Terminal and hit ‘return’

Then, you need to install ‘Yarn’

  • Type ”brew install yarn” into Terminal, and hit ‘return’

Step 2 Installing Node packages

Step 2a) Locating and linking folders on your machine

To enable DARIAH-Campus to run locally on your machine, you will need to install node packages. To do this:

  • Find the folder you want to connect to node.js in ‘Finder’ (this will likely be the ‘DARIAH-Campus’ folder that you use in Atom).
  • In Terminal, type ”cd” to change direction (also note, be sure to add a space after ‘cd’)
  • Drag and drop the folder from Finder into Terminal on the same line as “cd “. This will automatically write the ‘breadcrumb’ to the folder in Terminal.
  • Then type ”pwd” (path to working directory) in Terminal and hit ‘return’ This will show the correct breadcrumb trail to the folder to make sure you have the right one.

Step 2b) Installing node packages

  • Type ”yarn install” into Terminal (remember to hit ‘enter’). Installation may take a while if you haven’t installed this before. There is a progress bar on the bottom of Terminal that shows you how far along you are.

You are now ready to run DARIAH-Campus locally on your machine, so that you can preview any changes you make without having to commit them.

Step 3) Running and working with a local version of DARIAH-Campus

Step 3a) Installing the package to allow editing

  • Type ”yarn develop” (enter). This is the command to use if you want to develop the whole site, with all the necessary options for links and markdown, etc. This may also take a little while. If you do not have any problems installing this, proceed to Step 3c.

Step 3b) Troubleshooting any installation problems (if required)

  • Open GitHub Desktop.

  • Go to ‘Branch’ and select ‘Merge into Current Branch’, then select the most recent ‘upstream/master’ file. You will be asked to confirm the merge. Click on this.

  • You will probably then be prompted to ‘push to origin’ in the GitHub interface. This will push it to your local fork.

  • Review any changes, and then if you’re happy with them, click on ‘commit to master’.

  • Click on ‘push origin’.

  • In the box that comes up, select ‘open in Atom’.

  • In Atom, create a New File, and name it “.env.development”

  • In this file, copy and paste:

GATSBY_ALGOLIA_APP_ID=TTMMB715TN GATSBY_ALGOLIA_SEARCH_API_KEY=23e184697e638a863376dbd6c151a318 GATSBY_ALGOLIA_INDEX_NAME=dev_DARIAH-CAMPUS

  • Make sure there are three lines, all starting with ”GATSBY
  • Save this file.
  • Once this is saved, re-run installation of ‘yarn develop’ (as in Step 3a). This should now install correctly.

Step 3c) Editing a local version of DARIAH-Campus

You can now view dariah-campus in the browser using the link given to you in the terminal, which will look like this: ⠀ http://localhost:8000/

Copy the url given in Terminal into your browser, which will give you the DARIAH-Campus home page. Any saved edits you make to the DARIAH-Campus .mdx files in Atom will automatically be shown on your local version.

REMEMBER!! Any changes you make in Atom will only show up on your local version, but will not make any changes to the actual live version of DARIAH-Campus. This is useful if you want to try out a few things before updating. However, it’s important to remember that if you WANT to make changes to the live version, you will need to ‘commit’ them, ‘push origin’ and then ‘create a pull request’ so that the DARIAH-Campus editors can approve the changes.