Creating a new page
The overall process to create a page on the website is as follows
- Create a markdown file within the relevant section’s folder
- Add the page to the relevant sidebar
1. Create a markdown file
Each major section of the website has a folder within the pages
folder. All pages relating to that section have a corresponding markdown file within the folder.
Using the GitHub website interface
- Navigate to the relevant subfolder, e.g.
pages/legal_ethical
- In the top right, click on the ‘Add File’ dropdown, and click ‘+ Create new file’
- At the top, above the file contents, enter a short, relevant, underscore-delimited name
- Within the file contents, copy and paste a yaml header from an existing page and edit as needed
- Enter the page content using markdown syntax
- When happy with your draft, hit the green ‘Commit changes…’ button in the top right and enter a short message to describe what you have changed. We are happy to choose the default option of ‘Commit directly to the main branch’ at the moment. If you do want a specific review of your change, you can also choose to ‘Create a new branch for this commit and start a pull request’, and add a specific reviewer before your change will be incorporated into the website
- Once your commit has been incorporated into the main branch, it will trigger the website to rebuild. The progress of the rebuild can be monitored in the Actions tab. It should only take a few minutes. Once you see a green tick, it means it has completed and your new page should be live on the website and viewable by going to
https://australianbiocommons.github.io/human-omics-data-sharing-field-guide/<name_of_your_file_without_.md>
. Before your new page will appear in the sidebar you will need to follow the instructions below…
type
argument in the yaml header of the markdown fileSee the ELIXIR Toolkit theme documentation about section overviews or the Data repositories explained section for examples.
2. Add the page to the sidebar
All pages that are part of the main sections of the website, need to be added to the main sidebar before they will show up in the left-hand side navigation. All pages within the About section, need to be added to the about sidebar.
Using the GitHub website interface
- Open the relevant sidebar file within
_data/sidebars
, e.g.main.yml
- Click on the pencil icon in the top right to begin editing the file
- Find the relevant title of the section where you would like your page to be added
- Copy the pattern already in the file to add your page. Noting that the order in the sidebar will be as it is ordered in the file. Note that the hyphen and indentation should be consistent with the existing entries.
So the added text would look something like the block below:
subitems:
- title: New Page # The title of your page as it will show up in the side navigation
url: my_new_page # The exact name of your file without the .md extension
- Once you have added the page or pages to the sidebar, commit the file to main to trigger the rebuild.
- When the site has successfully rebuilt, check the sidebar has been updated but navigating to the page and refreshing
Editing an existing page
- Navigate to the page you want to edit on the website
- Click the pencil icon at the top of the page to the right of the page title
- This will take you to the relevant markdown page in the GitHub repo. Again, click the pencil icon at the top right of the page to begin editing the text
- Once you have finished editing, hit the green ‘Commit changes…’ button in the top right and enter a short message to describe what you have changed. We are happy to choose the default option of ‘Commit directly to the main branch’ at the moment. If you do want a specific review of your change, you can also choose to ‘Create a new branch for this commit and start a pull request’, and add a specific reviewer before your change will be incorporated into the website
- Once your commit has been incorporated into the main branch, it will trigger the website to rebuild. The progress of the rebuild can be monitored in the Actions tab. It should only take a few minutes. Once you see a green tick, it means it has completed and your edits should be live on the website and viewable by visiting the page and hitting refresh
Editing locally
For users who are comfortable interacting with GitHub via the commandline, a similar process as above can be followed as above by first cloning the repo, making changes as required, committing and pushing to the remote repository.
It is also possible (in theory) to run the website locally, see instructions on the ELIXIR toolkit theme README.