Creating / Editing a Pathfinder
The ‘Pathfinder’ resource on DARIAH-Campus offers a slightly different approach to sharing knowledge and training materials. They serve in many ways as a ‘state of the art’ / ‘literature review’ for a subject, but with a focus specifically on training materials. They are created in a very similar way to a ‘Hosted Resource’.
First things first, you need to start a new branch for your new resource. As has been shown in earlier sections, you can do this by first making sure you are on the ‘Main’ Branch, and then clicking the ‘Create New Branch’ button. You will be presented with a pop-up window where you can add your branch name, remembering to replace spaces with hyphens.
Adding the Pathfinder Resource Metadata
The metadata requirements for a pathfinder resource are less than for an external resource, but there are still some items to pay attention to.
The first field is the title of the pathfinder. This in turn generates the ‘slug’ for the url of the resource, based on the title.
You can then select the language of the pathfinder. This is through a dropdown menu. At the time of writing this documentation (March 2025) we only support two languages, but we hope this will change to allow you to add resources in other languages.
You are then asked to give the Publication Date. This publication date refers to the date that this resource is published to DARIAH-Campus. For that reason it defaults to whatever today’s date is. You should leave it at this, but you might be asked to update this when the resource is ready to be published following review from the Editorial Team.
Below this is the ‘Version’ number. By default this is set to 1.0.0. However, if you are making substantial changes to a resource (e.g. major content updates, not just typos), this will need to be changed to indicate that this is a new version. For now, though, as you are creating a new resource, you can leave this at the default setting.
Next you will need to add the Authors of your pathfinder resource. This is done using the people already published on the system. This field is both a search box and a drop down menu, but the quickest way to find someone is to start typing one or two letters of their name into the search field, and the drop down menu will filter down to only the named people with those letters in that order in their name. From there you can select which person you want to include. For resources with multiple authors you can repeat this step.
Once you have selected an author or authors, it will appear in a box below the drop down menu. For each person there is the option to change the order of authors listing, indicated by an icon featuring six dots, or the option to select that author, indicated by a checkbox, so that you can remove them from the list if required. Editors and Contributors are added in the same way.
Tags are selected in the same way as authors. You can use the search field next to the drop down button to start typing a topic, and select an appropriate tag from or tags from there. You can also re-order these by clicking on the 6 dots and dragging the tag up or down the list.
Sources are also selected in the same way. The ‘Source’ is used to assign a ‘channel’. In most cases, the source is ‘DARIAH’, unless you already have a dedicated ‘channel’ in place as agreed with the DARIAH-Campus Editorial Board.
You can also choose to add a ‘Featured Image’. Click on the ‘Choose File’ button. This will open the appropriate file management window for your operating system (e.g. Finder for Mac, File Explorer for Windows) to allow you to select an image from your own computer. One selected and confirmed, the featured image will be displayed as a thumbnail in this metadata field. You will also now have the option to remove this file if you choose.
Underneath this featured image field is the ‘Licence’ field. This is offered as a dropdown menu, but we only offer ‘CC-BY 4.0’ as an option, so you can leave this unchanged.
\
There is also a checkbox for whether or not to show a Table of Contents. The Table of Contents is generated using the headings you have in your pathfinder resource. This is useful for learners to navigate through your pathfinder, especially if it is a particularly long resource. You will also have noticed that we have a table of contents for this documentation. The Table of Contents checkbox is ticked by default, and we recommend that you make sure this is the case for your resource as well.
\
The Summary (formerly known as the ‘Abstract’) is the information that is displayed on the main ‘Resources’ page of DARIAH-Campus and offers a short preview into what the resource is about to entice the learner. The summary should be no longer than around 80 words, and should describe what is covered in the resource.
If the title of your resource is very long, you can also use the ‘Summary Title’ field to write a shorter, but still meaningful, title, and this will display on the Resources page.
If your event is in two or more languages, you can produce two different versions in those languages and then link them together using the ‘Translations’ field. To do this, ideally all versions are already published to Campus separately. You can then click on the ‘Translations’ field and start typing the name of the resource in its respective language to filter down the resources. Click on the resource and it will be added to the ‘Translations’ field.
The PID field is not editable, this is automatically generated when the resource is published, so you do not need to add anything here.
This completes all the metadata fields for a pathfinder resource, and at this point you can now ‘Create’ your initial draft by clicking on the blue button in the top right-hand corner of the screen. This will save all the metadata. Once you have created the draft, the blue button will change to say ‘Save’. We recommend that you save your work frequently to avoid any loss of content.
Writing the Content of your Pathfinder Resource
The large middle field in the CMS is your main content creation area. This is where you will write your pathfinder resource. There are a few things to keep in mind in relation to the house style, specifically around the types of headings used, and the order in which they appear. For that reason, as part of this step by step guide, an ‘Example Pathfinder Resource’ has been created for you to refer to when drafting up content. You can find the latest preview of the ‘Example Pathfinder Resource’ by clicking on the most recent ‘View Deployment’ on this Pull Request. You can view the House Style here.
First things first, get to know the different functions along the top formatting bar.
From left to right:
Paragraph Text style - this drop down menu allows you to determine whether something is normal paragraph text, or a specific heading type.
Bold, Italic, Strikethrough - these function the same as in other text editing software.
Inline Code - There are two ‘code’ icons on this formatting bar. This one on the left allows you to format one or more words in your paragraph as code. Use it for short snippets of code, variable names or short instructions.
Footnote - this icon allows you to create a footnote. Click on the icon and type in or paste in your footnote. This will appear as superscript, but in the published version that text will appear at the very end of the resource as a footnote, and a reference number will appear where you typed this text.
Campus Link - there are two ‘link’ icons. This first one to the left allows you to link to another resource or download within DARIAH-Campus. This is useful if you have related learning resources and want to guide users to them.
Clear Formatting - as in most document formatting, this allows you to clear all the formatting in selected text.
Bulleted List, Numbered List - allows you to add either a bulleted list or a numbered list to your text.
Divider - draws a solid straight horizontal line. This is useful if you want to separate sections even more clearly. You might place this underneath the ‘Learning Outcomes’ for example, to separate this from the rest of the actual resource.
External Link - This is the second of the two ‘link’ icons. For this link option it allows you to add any URL you want.
Quote Block- If you want to pull out some text to make it more memorable, or if you want to add a quote, this icon allows you to do this.
Code Block - This is the second of the two ‘Code’ icons. Use it for longer code examples or instructions that stand on their own like a paragraph. You can set the programming language in the pop-out window that appears in order to enable syntax highlighting. In the example below we set the programming language to ‘C’. You then type the code you want to include directly into the ‘Code Block’ box.
Table - Use this icon to add a table. It will show a 3 x 3 table by default, but you can edit this.
You can use all these options to draft up your content and make things a little more interesting for your learners. It also helps you to comply with the house style, including adding the correct heading types, and formatting for required elements.
You can make things even more interesting for your learners by making use of Widgets, which are detailed below.
Making use of the Widgets
You will have noticed that the final button on the formatting bar was not mentioned above. This is the ‘Widgets’ drop down menu, and this contains other options you might want to include in your hosted resource. These are all explained below, in the order they appear on the drop down menu.
Call out / Sidenote
If you want to highlight some information, or give a warning or a tip within your learning resource, a ‘Callout’ (otherwise called a ‘Sidenote’) can do this for you.
When you first click on this option, a blank ‘Note’ box will appear where you had your cursor. At the same time, a ‘pop-up’ will appear allowing you to edit this. You can choose from different types of call out, and this will determine the colour of the box when it appears in the resource. You can also edit the title of the note, leaving it as its default, or changing it to something more specific to your content.
Once your resource is published, your callout (sidenote) will look something like this:
Disclosure
A ‘Disclosure’ allows you to insert text that is hidden behind an interactive ‘toggle’, allowing the learner to reveal further information or content. You could use this for self-assessment, posing a question and then revealing the answer on a click. Or you could use it for more in-depth content such as case studies, or a further reading list.
Best practice for accessibility recommends putting items like disclosures, quotes or tabs into a call out box (see above), as this identifies the item as an ‘asset’ for screenreaders. You should add a ‘plain’ callout and then you can add the ‘disclosure’ widget inside the callout box by clicking to bring the cursor into the box in the same way you would start typing, and then selecting ‘disclosure’ (or indeed ‘tab’) from the widget menu.
When you click on the disclosure widget option, an editable version will appear. Click on the ‘edit’ button to open a pop-up window that asks you to give it a title.
Once you have entered a title, you can then type directly into the text box below to add the additional information. Within the CMS you will be able to toggle the disclosure to open and close it, giving you an indication of how this will appear once it is published.
Embedding a Webpage
Sometimes it is useful to be able to bring in elements from other websites, particularly if their interactive elements are not currently compatible with the DARIAH-Campus architecture. An example of this could be Jupyter Notebooks, which cannot currently be integrated into DARIAH-Campus resources. A work-around for this could be to embed the webpage the Jupyter Notebook is published on, and allow learners to interact through that.
In this example we’ll use the DARIAH.eu website to demonstrate this.
Select the ‘Embed’ option from the widget dropdown menu. When you do this, a blank box with an ‘Edit’ button in the right hand corner will appear. Click on this, and a pop-up window will appear for you to type in the full URL (don’t forget the ‘https://www’ bit!) for the webpage you want to embed.
The webpage will then be displayed in that embed box. Click ‘Done’, and that’s it! If the webpage is quite long, a scroll bar will also appear on the right-hand side. When the resource is published, it will look almost identical to how it appears in the preview.
Figure
You may want to include images or infographics in your pathfinder resource. This is also very straightforward. When you select the ‘Figure’ widget, a blank box appears on the page with an ‘edit’ button in the top-right hand corner. Click on this and it will open a pop-up window. You first click on the ‘Choose file’ button to open your computer’s file manager to find an image to add. A thumbnail of the image will be displayed below.
From here you can then add ‘Alt Text’ in the field for ‘image description for assistive technology’. While this field is currently not a required field, it is highly recommended that you add Alt Text to support screen reading technology. If the image is purely decorative, or is described and explained in the accompanying text in the resource, you can type in either the empty alt attribute ” ”. For more notes and information on when Alt Text is required, you can visit the W3 Alt Text Decision Tree here: https://www.w3.org/WAI/tutorials/images/decision-tree/. For tips on writing useful Alt Text, we recommend taking a look at the AxessLab notes on writing Alt Text here: https://axesslab.com/alt-texts/.
Finally, you can decide whether you want the image to stretch across the page, or to be aligned centrally.
Once you have edited the image box, the image then appears on the page. You are then encouraged to write in a caption directly in the box underneath the image.
Adding a Grid Layout
A grid layout offers an interesting way to present information, particularly if you want something similar to a table without having gridlines. Once you have selected the ‘Grid’ option, and clicked on the ‘edit’ button in the box, a pop-up window appears with two drop-down menus.
The ‘Layout’ drop-down menu allows you to pick how many columns and rows you would like, along with how wide you would like each column to be. The ‘Vertical Alignment’ drop-down menu determines whether text fills the cell it’s in, or sits centrally within it.
Once the layout has been fixed you can then ‘insert’ cells into your grid and then start writing in text directly to each new box. If you add to many cells, or grids within grids, you can click on the ones you want to delete to select them (turns blue), and tap your delete key.
Once published, the text will appear in the layout you determined, without any gridlines or boxes.
Heading ID
Each heading has an automatic heading ID based on the text used in that heading. For example, if you have a heading that says ‘Introduction’ then that becomes its heading ID. These IDs can be used to link to the different sections in the document, such as in a Table of Contents, or if you are adding a bookmark or anchor manually. Sometimes, you might want to change the heading ID to fit a format, for example, if the heading is too long to be a memorable URL fragment and you want to keep it simple. Heading ids should follow the pattern of lower case text with hyphens between words, for example:
Heading title: “Exploring AI in historical linguistics: The role of pattern recognition”
headingId: ai-in-historical-linguistics-pattern-recognition
Place your cursor next to the heading you want to alter, and click the ‘Heading ID’ option from the widget menu. A grey hashtag will appear. Click on the hashtag and select the edit icon (a pencil). This brings up a pop-up window where you can then type in the text you would like to appear in its URL. Once you have confirmed this by clicking ‘done’, the grey hashtag now shows the alternative title you have given this heading.
Link Button
A link button is a visually appealing way of adding a hyperlink or download option to your resource. Once you have selected the link button option, the blank box appears on the page. Click the edit button to bring up the pop-up edit window. You will see a drop-down menu labelled ‘Kind’ that allows you to determine what kind of item you want to link to (a direct URL, a download of a document, for example). Once this has been selected, you can then enter the URL for the item.
The link button now has a URL attached to it. You can then click in the link button itself to type in a title or a call to action such as ‘Click here to visit such-and-such website’.
Tabs
Tabs offer a different layout for text, particularly if that text is related in some way. They work in a similar way to the ‘disclosure’ option in that they can reveal text, but more than one tab can be added to a block.
As for the ‘disclosure’ widget, it is good practice to place your tabs within a plain ‘callout’.
After you click on the ‘Tabs’ option, the box appears on the page. From here you can use the button on the right of the box to ‘Insert’ as many tabs as you would like. These all appear below as individual tab boxes. In each tab box, you can then click the ‘Edit’ button to give each tab a title. From there you can then enter the content you want to include in each tab by typing directly into the box underneath its title.
When this is published, the tabs all appear lined up horizontally, and are clickable to reveal the text.
Video
The ‘Video’ option allows you to embed a video within the content of the pathfinder resource you are writing. This is particularly useful if you want to embed a video to illustrate or demonstrate an issue or provocation.
In the ‘Edit’ box of your video field, first select your video host (YouTube, Vimeo, Nakala or University of Helsinki). You will also be asked again for the video ID. The ‘Video ID’ can be found usually at the end of the URL for the video. In the case of YouTube, for example, this is typically around 11 or so characters in length, usually made up of alpha-numeric characters and symbols. If you have a specific start-time in the video that you want people to see, you can enter that in the ‘Start time’ field.
Once you have entered all this and clicked ‘Done’, the video thumbnail will appear in the ‘Video’ box. You can type a caption for the video directly underneath to let users know what they are looking at.
Remember to save your work as you go along!
Finishing Touches
Before you send off your pathfinder for review, take a moment to check that you have all the required metadata fields filled in, that you have an introduction, learning outcomes and a conclusion that summarises what has been covered in the pathfinder resource and how they relate to the learning outcomes.
Saving your Pathfinder Resource for Publication
After doing so much work, you may wish to ‘Create’ a pull request, and save your work. You can of course do this at any point in the editing process once the required event metadata has been entered. Exactly when you choose to create the pull request and save your work is up to you, depending on your own practices, although we recommend saving frequently after a set of changes to ensure nothing is lost in the unlikely event of a website crash, or if you have to step away from your computer.
To create a draft, click on the blue button in the top right-hand corner of the screen saying ‘Create’. Once you do this, a green message will display momentarily at the bottom of the screen saying ‘Entry Created’. The blue button will now change to say ‘Save’.
Now you have saved your resource, and are happy that it has all the information you want to include in there, you can save the resource again, and then move to create a pull request.
Click on the ‘Branch Options’ button (three horizontal dots, next to the Branch Dropdown menu), and select ‘Create Pull Request’.
This will bring you to the GitHub site, where you can create the Pull Request by clicking on the green button halfway down the page saying ‘Create Pull Request’ (depending on your screen size, you may have to scroll down to see this button).
The screen will now change to show you the actual pull request that your draft is filed in on GitHub. After a short while, a ‘Vercel bot’ will post an automatic message to the Pull Request which includes a table showing a summary of the latest updates. In this table you will see a link to ‘Visit Preview’.
This link will always bring you to the latest successfully built preview of your resource. You can click on this to see how your resource looks on the DARIAH-Campus website. Do note, this is only a preview link, and should not be shared in any official capacity.