Add, Edit & Publish Documentation
Publishing documentation to docs.nhmlac.org requires a GitHub account and permission to the NHMLAC GitHub organization. Please contact the NHMLAC developers to gain access.
Adding new documentation to docs.nhmlac.org requires either working on GitHub.com or using an IDE of choice. For users with experience with Git who would like to work locally, please refer to the Installation Guide for instructions on how to set up a local environment.
For users without much Git experience, using GitHub.com is recommended. While GitHub.com does have a text editor, using an editor made for markdown, such as Typora (opens in a new tab) might also be beneficial. This documentation will walkthrough how to commit changes to NHMLAC's repository so that new content can be displayed on docs.nhmlac.org.
Github Workflow
Committing to a GitHub repository can be done via the CLI (command line interface) or on github.com's GUI. If familiarity with Git or using a computer's terminal is limited, commiting on github.com GUI is the recommended workflow. Steps to publish documentation on github.com are as follows:
Navigate to the repository
NHMLAC's dev documentation can be found here https://github.com/naturalhistorymuseumofla/nextra-docs (opens in a new tab). If you don't have access to the repository, please contact the NHMLAC developers to gain access.
Create feature branch
Never edit content directly on the "main" branch. Always edit on a feature branch.
Creating a branch is essentially a copy of the repository where changes can be made.
- Click on
branches.
- Click on
New Branchbutton located at the right corner to create a new feature branch.
- Click the dropdown on the lefthand side of the page (see screenshot below) and select the newly created branch. In the example below, a branch named "testing" was created.
Adding or Editing Content
To see a detailed guide on how to manage files on GitHub.com, please consult Editing Files (opens in a new tab)).
To edit an existing file, Navigate to the file you want to edit using the side panel (see below). Folders in the side panel can be expanded by clicking the arrow next to the folder name.
To add a new file or folder to the repository, click the "Add file" button on the top right of the repository page. A dropdown will appear with options to either "Create a new file" or "Upload files".
After selecting "Create a new file", add content in the Edit pane. Name the file with the approriate file extension (e.g. .md for markdown files or .mdx for MDX). To add a folder, add a backslash (/) after the folder name (e.g. folder-name/).
3. Commit changes
After edits have been made, press the green "Commit changes" button on the top right. Commiting on GitHub is similar to saving a file.
After "Commit changes" is clicked, a popup will display that requires a "Commit message" to be entered. A commit message should be a short, one sentence long title that briefly summarizes the changes made. Use the "Extended description" field for a lengthier summary, though it is not required.
Once ready, click the "Commit changes" button on the popup window.
4. Create a Pull Request
Click the "Pull requests" in the upper tabs pane (see below).
In the orange alert callout, click the "Compare & pull request" button.
On the "Open a pull request" page, include a title and message about the commit. The title should be a short description briefly summarizes the changes made, similar to a commit message. Use the "Write" field for a lengthier summary, though it is not required.
Click "Create pull request" to finalize your pull request. Please notify code owner, either by messaging him/her (usually a developer) or by requesting that person under "Reviewers" on the right panel of the PR window.
5. Wait for changes to be approved and merged
Once a reviewer approves the Pull Request, the changes will be approved and merged into the main branch. The branch will be automatically deleted, and changes be reflected on hte deployed documentation site.
