Merge pull request #84 from OpenGeoMetadata/83-update-readme

Update README.md

Author: karenmajewicz

README.md

@@ -34,11 +34,11 @@ This is the working branch containing the content for the site using Markdown.
 * **mkdocs.yml**: the configuration file that identifies the theme, the extensions, and the navigation
 * **docs** folder
 	*  Markdown documents: The content for the site. These can all live in the same directory and are organized in the public navigation menu in the nav section of **mkdocs.yml**.
-	*  	`/ogm-aardvark`: a subfolder with markdown files for each element in the Aardvark schema
-	*  	/`images : JPGs, PNGs, and other image files
+	*  	`/ogm-aardvark`: a subfolder with CSV files for each element in the Aardvark schema
+	*  	/`images` : JPGs, PNGs, and other image files
 	*   `/javascripts/tablesort.js`: the javascript function that allows users to sort tables online
 	*   `/stylesheets/extra.css` : a CSS file that can define colors, fonts, and other customizations for the site
-	*   `/tables` : CSV files for any information to be included in tables
+	*   `/tables` : CSV files for any general information to be displayed as tables
 
 
 ### gh-pages branch
@@ -54,63 +54,88 @@ This is the published branch containing the HTML code for the site. (We do **not
 
 ## Updating the OpenGeoMetadata website
 
-Since this site is written with Markdown files, the minimum requirement to contribute is to just edit or submit new Markdown files.  However, MkDocs is relatively simple to install and run locally. This allows you to preview changes locally before submitting them.  To get started, visit the Material for[ MkDocs Getting Started page](https://squidfunk.github.io/mkdocs-material/getting-started/) and choose an installation method.
+Since this site is written with Markdown files, the minimum requirement to contribute is to just edit or submit new Markdown files.  However, MkDocs is relatively simple to install and run locally. This allows you to preview changes locally before submitting them.  
 
-:triangular_flag_on_post: *This workflow uses the [MkDocs deploy technique.](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-mkdocs) We may want to consider using [GitHub actions](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions) instead.*
 
-### Workflow overview
+To get started, follow the steps below.  It may also be helpful to visit the Material for[ MkDocs Getting Started page](https://squidfunk.github.io/mkdocs-material/getting-started/) and for reference.
 
-![](docs/images/github.png)
+### Install Material for MkDocs
 
-:warning: This workflow may vary from how you collaborated on other GitHub Pages sites, because we don't do Pull Requests to the branch that is actually being published (gh-pages). The site is always published from a command line interfaces using `mkdocs gh-deploy`.
+1. Open the Terminal and type the following:
 
-MkDocs offers two commands to run in Terminal/Command Line for simplifying the process of editing and publishing GitHub pages:
+`pip install mkdocs-material`
 
-* `mkdocs serve`: this will start a local server so you can preview the site as you build it. 
+This command will install all the necessary modules for the mkdocs platform and the Material theme together.
 
-* `mkdocs gh-deploy`: this will convert all of the Markdown documents to HTML and publish them to a branch called **gh-pages**.
 
+2. Next, install the Table Reader plugin:
 
+`pip install mkdocs-table-reader-plugin`
 
-### Workflow steps
+This plugin converts the CSV tables to be rendered as HTML in the website.
 
-Contributor:
+### Edit the website
 
-1. Update your local instance of the OpenGeoMetadata repository
-2. Make a new branch and switch to it
-3. Edit the Markdown files
-4. Preview the site locally using `mkdocs serve`
-5. Commit your changes
-6. Publish your branch
-7. Open a Pull Request to the main branch
+1. Clone or fork the opengeometadata.github.io repository
 
-Publisher:
+2. Make a new branch
 
-1. Accept Pull Request and merge changes to the main branch
-2. Update your local instance of the OpenGeoMetadata repository
-3. Stay or switch to the MAIN branch
-4. Preview the site locally using `mkdocs serve`
-5. Publish to GitHub with `mkdocs gh-deploy`
+3. Change into the opengeometadata.github.io directory and type:
+
+`mkdocs serve`
 
+This will start a local server so you can preview the site as you build it. You will see text in the Terminal that looks something like this:
 
+```
+INFO     -  Documentation built in 4.15 seconds
 
+INFO     -  [14:43:24] Watching paths for changes: 'docs', 'mkdocs.yml'
 
+INFO     -  [14:43:24] Serving on http://127.0.0.1:8000/
 
+INFO     -  [14:43:31] Browser connected: http://127.0.0.1:8000/
+```
+4. In a browser, open the locally hosted site at http://127.0.0.1:8000/ (or whatever your Terminal shows)
 
+5. Edit the markdown files and preview them in your browser.
 
+6. When you are ready to publish the changes, commit them locally using GitHub Desktop or a Terminal command.
 
+7. Publish the branch and open a pull request to the Main branch.
 
 
+### Workflow steps overview
 
+Contributor:
 
+1. Clone or update your local instance of the OpenGeoMetadata.github.io repository
+2. Make a new branch and switch to it
+3. Edit the Markdown files
+4. Preview the site locally using `mkdocs serve`
+5. Commit your changes
+6. Publish your branch
+7. Open a Pull Request to the main branch
 
+Publisher:
 
+1. Accept Pull Request and merge changes to the main branch
+2. GitHub Actions will automatically push the changes to the gh-pages branch
 
 
+### Differences from local server previews and public view
 
+As of April 2023, the opengeometadata.github.io site is being published via the sponsored version of Material for MkDocs, known as "[Insiders](https://squidfunk.github.io/mkdocs-material/insiders/)." This enables a few extra features that you will only see online, not in your local instance, including:
 
+* breadcrumbs
+* emojis on the tabs
+* admonitions
 
+We will reassess this in a few months to determine if it is a viable model going forward.
 
 ------
 
-All questions about this repository and contributing to it or other elements of the OpenGeoMetadata project can be directed to geoblacklight-working-group@googlegroups.com.
+Questions about this repository or other elements of the OpenGeoMetadata project?
+
+Submit metadata related issues here: https://github.com/OpenGeoMetadata/metadata-issues/issues
+
+Report bugs and typos on the website itself here:  https://github.com/OpenGeoMetadata/opengeometadata.github.io/issues