Juncture Site Quick Start

In addition to providing code for transforming simple text files into interactive web pages, Juncture can also be used to transform multiple text files into a fully functioning website with headers, footers, navigation menus, contact forms, etc. Juncture is a framework designed to be customized and extended. This extensibility provides limitless possibilities.

In this quick start guide we will create a simple website that uses the Github Pages domain. A custom domain can easily be associated with the site if desired.

There are a couple of methods for creating a Juncture-powered web site. In this guide we will use the Fork method which is the easiest and would suffice for most users. Other methods are available {{TODO}}.

A fork is a simply a full copy of a Git (Github) repository, in this instance the Juncture repository. The forked repository is an exact copy of the source repository at the time of forking.

Create a new Juncture Site

To create a new Juncture site using the fork method:

1. Navigate to the Juncture repository page and select the Fork button found at the top-right of the page. After pressing this button a full copy of the Juncture repository contents will be copied into your person Github account. Note that after the forking has been performed (it only takes a few seconds) your browser page is opened in your forked copy.
2. From your forked copy of the Juncture repository select the Settings button from the menu in the top section of the page. From this Setting page:

• In the main Options tab, rename the repository, if desired
• In the Pages tab, enable GitHub pages by selecting the main branch option in the Source pulldown selector and press the Save button.

At this point you will have a functioning Juncture site that can be accessed from the Github Pages URL https://<YOUR-GH-USERNAME>.github.io/<YOUR-GH-REPOSITORY> (replacing the <YOUR-GH-USERNAME> and <YOUR-GH-REPOSITORY> vales with your Github username and the name of the forked repository). Note that the Github Pages URL may initially return a 404 Not Found error. This is not uncommon for a few minutes after a repository is created and configured for Github pages hosting. If so, check back occasionally. The link will eventually work.

Customize your new Juncture Site

A new Juncture site that has been created by forking will include the same content as the source repository. In this section we will make a couple of simple updates to illustrate the basic process for updating existing content or adding new content. Refer to this documentation page for a more comprehensive treatment of Juncture site customization.

Update the home page

1. Navigate to the home page for your new Juncture repository, the URL will be https://github.com/<YOUR-GH-USERNAME>/<YOUR-GH-REPOSITORY>
2. From the repository home page select the edit button (the pencil icon found in the top-right section of the document viewer pane). This will open the Github text editor in your browser.
3. Add, remove, or update the text as desired. A Preview tab is available at the top of the editor window to view changes prior to saving.
4. Save the changes by selecting the green Commit changes button found at the bottom of the page. Note that optional fields are available in the Commit changes form for adding a title and/or description of the change.

After saving (committing) your changes the updated home page will be visible on from the rendered site, using your sites Github Pages URL (https://<YOUR-GH-USERNAME>.github.io/<YOUR-GH-REPOSITORY>).

Change the sites default title, tagline, and banner image

A title, tagline (or author name), and banner image can be defined for each page (visual essay) on the site. The site also provides defaults for pages that do not explicitly one or more of these values. The site defaults are defined in a configuration (name config.yaml) file located at the root of the repository. The initial version of a forked Juncture repository does not contain a config.yaml file. A template for this file is provided to get started.

1. Copy the contents of the config template. - Navigate to the home page for your new Juncture repository, the URL will be https://github.com/<YOUR-GH-USERNAME>/<YOUR-GH-REPOSITORY> and copy the contents of the config.template.yaml file. This can be done by clicking on the config.template.yaml file name in the file list and then clicking on the Raw button found in the file tool bar. After clicking the Raw button the contents of the file will be shown in the browser window. Select and copy the page contents.
2. Paste the template text into new config file - Return to the repository home page and select the Create new file option from the Add file dropdown menu found in the top section of the page. In the new file form enter config.yaml in the fine name input field (with Name your file... placeholder). Paste the copied text from the template into the text editor pane and press the green Commit new file button to create the new config file.
3. Modify the contents of the new config.yaml file - Try changing the Title, tagline and banner values (note that the banner value must be a valid image URL). Save the updated file using the Commit changes button. Below is an example of an updated config file.

title: My new Juncture site
tagline: With a custom tagline
banner: https://upload.wikimedia.org/wikipedia/commons/c/c4/Himalayas_in_the_morning_light.jpg
#favicon: <favicon url>
#logo: <logo url>

# When using a custom domain these fields must be updated to match
# the Github account and repository name
#acct: <GitHub account/username>
#repo: <GitHub repository>

######################################################
# Defines options shown in the header navigation menu
######################################################
nav:
- label: View page source
  icon: fas fa-file-code
  action: view-markdown

Add and link a new page

In this example we will add a new page to the site and create a link to it on the home page.

There are two options for creating a new page. The first is to simply create the new file with a .md file extension, for example, sample-essay.md. The second (and recommended) option is to create a folder with the desired name (without the .md extension) and in that folder create a README.md file for the page contents. The second approach has the advantage of providing a folder for holding any resource files (like local images) that might be used in the page. In this example we will use the folder approach.

1. Create a folder and README.md file - Again, navigate to the home page for your new Juncture repository and select the Create new file option from the Add file dropdown menu. In the file name input field enter sample-essay/README.md. In the editor pane for this new file, copy/paste the contents of the sample visual essay page. After the text has been added save the file using the Commit changes button.
2. Create a link to the new page on the home page - From the repository home page click the edit button (pencil icon) and add the following text somewhere on the page and save the updated file.

This is a link to [my new essay](sample-essay).

3. View the added essay using the new link - Use the site Github Pages URL (https://<YOUR-GH-USERNAME>.github.io/<YOUR-GH-REPOSITORY>) to view the updated home page and click on the my new essay link. If everything worked the new visual essay should be displayed.

Add new page to site navigation menu

In this example we will an entry in the site navigation menu for our new essay.

1. Open the site config file - From the repository home page click on the config.yaml file and then click on the edit button. In the editor pane add the following text below the existing entry in the nav section of the file and save the updated file.

- label: My new essay
  icon: fas fa-file-code
  action: load-page
  path: /sample-essay

2. View the added essay using the new menu item - Use the site Github Pages URL (https://<YOUR-GH-USERNAME>.github.io/<YOUR-GH-REPOSITORY>) to view the site home page and click menu button in the top left corner of the header. From the menu select the My new essay link. Again, if everything worked, the new essay page will display.

Regarding the menu icons: Juncture uses the [Font Awesome] icon library. The free icon set can be seen at https://fontawesome.com/v5.15/icons?d=gallery&p=2&m=free. To use a different icon for the menu replace the text in the icon: field with the new value.