Skip to content

Contribute

Guide for Contributing to the CUAHSI Water Content Portal

This guide outlines the process for contributing content to the CUAHSI Water Content Portal, which is hosted through Netlify and built using mkdocs. We welcome proposals for updates, new pages, or improvements. All content in this platform is managed in version control using GitHub, a tool that facilitates collaborative change tracking and maintains an accurate revision history.

Quick Start Contribution Options

Note on GitHub Account: For options 1 and 2 below, you will need a GitHub account. If you don't have one already, you will need to go to https://github.com to create a user account, or you can use for option 3 (Send us an email!) for suggesting edits or content.

  1. Create a GitHub Issue. You can suggest edits or content by creating an issue in the main GitHub repository (https://github.com/CUAHSI/Water-Content-Portal).
    • Process: Post your suggested edits, new content ideas, or external content proposals in the issue. This is also the best method for submitting content that is not currently in a GitHub repository.
    • Discussion: Others can comment and discuss the suggestion before any changes are made to the page itself.
    • Tracking: Keep an eye on your GitHub notifications to follow how your suggestion is being implemented.
    • Addition note on external content proposal: If you are proposing content not in GitHub, please include details on where the file lives (e.g., a link or storage location), the file name, and any relevant rendering information so that we can ingest and render the outside content properly. Alternatively, you may reach out to help@cuahsi.org to initiate the contribution process for external content.
  2. Direct Edits in GitHub. For those comfortable suggesting edits directly to the content already in the repository, you can use direct browser editing or make edits on your local machine that can be pushed to GitHub. If you have write access, you can follow a process similar to the one outlined in the reference document for editing:
    • Create a new branch.
    • Find the file you wish to edit.
    • Edit the file directly in the browser editor and commit changes to your new branch. Remember the website uses Markdown (.md) for text.
    • Start a pull request to get your changes reviewed and merged into the main branch.
  3. Send us an email! Send us an email directly at help@cuahsi.org with your suggested edits or content to the platform.

Contributing Content already living in a seperate GitHub repository

Our platform is configured to support Git submodules, which allows us to embed content from other repositories (like yours) into the portal. If you have content in a separate GitHub repository (e.g., a tutorial, documentation, or textbook) that you would like to contribute:

  • Create a New Issue: Start by following the Create an Issue step above.
  • Provide Repository Details: In the issue, clearly specify:
    • The GitHub URL of your repository.
    • The specific file name(s) or folder(s) you want to include in the portal.
    • The desired location and title within the portal's navigation structure (which is defined in mkdocs.yml).
  • Core Team Action: A core team member will be responsible for:
    • Adding your repository as a Git submodule.
    • Updating the main project's mkdocs.yml file to include the paths to your documentation files in the navigation (nav section).