Post-collab guide updates

.gitignore

@@ -4,3 +4,6 @@
 # Additional
 __pycache__
 
+# MkDocs build output
+site/
+

.markdownlint.json

@@ -1,5 +1,8 @@
 {
   "MD007": { "indent": 4 },
   "no-hard-tabs": false,
-  "MD013": false
-}
+  "MD013": false,
+  "MD026": { "punctuation": ".,;:" },
+  "MD040": false,
+  "MD046": false
+}

.markdownlintignore

@@ -0,0 +1,2 @@
+docs/wiki-guide/HF_*_Template*.md
+mkdocs.yaml

CITATION.cff

@@ -1,22 +1,31 @@
-abstract: "Imageomics-focused guide to collaborative work, including GitHub and Hugging Face workflows."
+abstract: "Template guide site for collaborative work, including GitHub and Hugging Face workflows."
 authors:
 - family-names: "Campolongo"
   given-names: "Elizabeth G."
   orcid: "https://orcid.org/0000-0003-0846-2413"
 - family-names: "Thompson"
   given-names: "Matthew J."
   orcid: "https://orcid.org/0000-0003-0583-8585"
-- family-names: "Zoe"
-  given-names: "Duan"
+- family-names: Zhang
+  given-names: Net
+  orcid: "https://orcid.org/0000-0003-2664-451X"
+- family-names: "Duan"
+  given-names: "Zoe"
   orcid: "https://orcid.org/0000-0002-8547-5907"
 - family-names: "Bradley"
   given-names: "John"
   orcid: "https://orcid.org/0000-0003-3858-848X"
+- family-names: Eyriay
+  given-names: Iuliia
+  orcid: "https://orcid.org/0009-0007-1597-8684"
+- family-names: Taylor
+  given-names: Graham
+  orcid: "https://orcid.org/0000-0001-5867-3652"
 - family-names: "Lapp"
   given-names: "Hilmar"
   orcid: "https://orcid.org/0000-0001-9107-0714"
 cff-version: 1.2.0
-date-released: "2024-11-DD"
+date-released: "2025-06-DD" # to update on release
 identifiers:
   - description: "The GitHub release URL of tag v1.0.0."
     type: url

CONTRIBUTING.md

@@ -0,0 +1,234 @@
+# Contributing to the Imageomics Guide
+
+Thank you for your interest in contributing to the Imageomics Guide!
+
+This document outlines the standards and guidelines for contributing to the Imageomics Guide. Before you begin, please review the information provided here.
+
+First, is your contribution specific to Imageomics, or would it be more broadly applicable? If more general, please consider instead directing the update or suggestion to the [Collaborative Distributed Science Guide](https://github.com/Imageomics/Collaborative-distributed-science-guide); updates to the template repository will be incorporated both here and in other other guides developed from it. If it _is_ Imageomics-specific, please continue to review this document—we look forward to your input!
+
+## Overview
+
+The Imageomics Guide is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) and deployed via GitHub Pages. All documentation is written in Markdown and follows specific formatting standards to ensure consistent rendering and maintainability.
+
+## Getting Started
+
+### Local Development Setup
+
+1. Clone the repository
+2. Set up a virtual environment (recommended):
+
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+   For more detailed environment setup options (including conda), see our [Virtual Environments guide](docs/wiki-guide/Virtual-Environments.md).
+
+3. Install dependencies:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. Serve the site locally:
+
+   ```bash
+   mkdocs serve
+   ```
+
+5. View the site at <http://127.0.0.1:8000/Imageomics-guide/>
+
+### Testing Changes
+
+Always test your changes locally with `mkdocs serve` before submitting a PR to ensure:
+
+- Content renders correctly
+- Links work properly
+- Formatting appears as intended
+- No build errors occur
+
+## Documentation Standards
+
+### Markdown Formatting
+
+#### Indentation for Nested Lists
+
+- **Use 4 spaces for nested list items** (not 2 spaces)
+- This requirement exists due to Python-Markdown compatibility issues with MkDocs
+- 2-space indentation causes nested lists to not render properly in the final HTML
+
+**Correct:**
+
+```markdown
+- [ ] Main item
+    - [ ] Nested item
+    - [ ] Another nested item
+```
+
+**Incorrect:**
+
+```markdown
+- [ ] Main item
+  - [ ] Nested item (will not render as nested)
+```
+
+#### General Formatting
+
+- Remove trailing whitespace
+- Use consistent line breaks
+- Follow the project's `.markdownlint.json` configuration
+- Ensure proper heading hierarchy (don't skip heading levels)
+
+### License Format Requirements
+
+#### Hugging Face YAML Frontmatter
+
+When specifying licenses in Hugging Face dataset/model card YAML sections, **always use lowercase**:
+
+**Correct:**
+
+```yaml
+license: cc0-1.0
+```
+
+**Incorrect:**
+
+```yaml
+license: CC0-1.0  # Will cause issues with Hugging Face platform
+```
+
+This is a platform-specific requirement for Hugging Face compatibility.
+
+#### License References in Text
+
+In prose text, you may use standard capitalization (e.g., "CC0", "MIT"), but YAML frontmatter must be lowercase.
+
+### File Organization
+
+- Documentation content goes in `docs/`
+- Wiki-style guides go in `docs/wiki-guide/`
+- Images and assets are organized in subdirectories within `docs/`
+- Templates use descriptive filenames with consistent naming patterns
+
+### Custom Macros
+
+The project includes custom MkDocs macros defined in `main.py`:
+
+- `include_file_as_code()` - Embeds file content as code blocks
+- When using macros, ensure proper syntax and test rendering locally
+
+## Contribution Process
+
+1. **Create an issue** describing the change (for significant additions)
+2. **Create a feature branch** from `dev`
+3. **Make your changes** following the standards above
+4. **Test locally** with `mkdocs serve`
+5. **Run linting (OPTIONAL)** to ensure formatting consistency
+   - See instructions in [Linting](#linting)
+6. **Submit a pull request** with:
+   - Clear description of changes
+   - Reference to related issue
+   - Screenshots if UI changes are involved
+
+### Pull Request Guidelines
+
+- Keep PRs focused on a single topic when possible
+- Follow commit message conventions (see below)
+- Update navigation in `mkdocs.yaml` if adding new pages
+- Ensure all links work correctly
+- Test that the site builds without errors
+
+### Commit Message Guidelines
+
+The most important aspects of good commit messages are that they should be **descriptive** and **atomic** (each commit should represent a single logical change). Additionally:
+
+- **Keep the first line short**: Limit the subject line to 50 characters or less
+- **Use the imperative mood**: "Add feature" not "Added feature" or "Adds feature"
+- **Separate subject from body**: Use a blank line between the subject line and detailed description
+
+#### Conventional Commits Recommendation
+
+We recommend following the [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages:
+
+**Format:** `type(scope): description`
+
+**Common types:**
+
+- `feat`: New feature or content addition
+- `fix`: Bug fix or correction
+- `docs`: Documentation updates
+- `style`: Formatting changes (no content changes)
+- `refactor`: Code/content restructuring without changing functionality
+- `chore`: Maintenance tasks, tooling updates
+
+**Examples:**
+
+```bash
+feat(fair-guide): add data repository checklist
+fix(templates): correct license format in HF dataset card
+docs(contributing): add conventional commit guidelines
+style(checklists): fix markdown formatting and indentation
+chore: update mkdocs dependencies
+```
+
+**Scope** is optional but helpful for larger changes. Use the guide section or file type being modified.
+
+**Note:** Since we use squash merges, strict adherence to this format isn't required, but descriptive and atomic commits help maintain a clear project history.
+
+## Quality Assurance
+
+### Linting
+
+The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`. Key settings:
+
+- 4-space indentation for lists (`MD007`).
+- No hard tab restrictions disabled.
+- Line length restrictions disabled (`MD013`).
+- Restrict punctuation in headers (`MD026`); allow `!` and `?`.
+- Allowed code blocks without language specification (`MD040`).
+- Allow fenced code blocks, as this commonly errors when indented (see [discussion](https://github.com/DavidAnson/markdownlint/issues/327)).
+
+For faster PR review, you may want to run linting locally; we do have a PR Action in place as well. First install markdownlint, then run
+
+```console
+markdownlint -c .markdownlint.json -f docs/wiki-guide/
+```
+
+The `-f` resolves simple formatting issues, and alerts will be raised for more complicated linter style rules (e.g., referencing a link as `[here](URL)` will produce the line: `<filename>.md:191:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]`).
+
+### Content Review
+
+When reviewing content:
+
+- Verify accuracy of technical information
+- Check for consistency with existing guides
+- Ensure proper cross-referencing between related pages
+- Validate that external links are current and working
+
+## Platform-Specific Considerations
+
+### Hugging Face Integration
+
+- Dataset and model card templates must follow HF specifications
+- YAML frontmatter formatting is critical for platform compatibility
+- License identifiers must match HF's expected format
+
+### MkDocs/Python-Markdown
+
+- Nested list rendering requires specific indentation
+- Some Markdown extensions may behave differently than GitHub Flavored Markdown
+- Always test complex formatting locally
+
+## Getting Help
+
+- Open an [issue](https://github.com/Imageomics/Imageomics-guide/issues) for questions or problems
+- Reference existing guides and templates for examples
+- Check the [MkDocs Material documentation](https://squidfunk.github.io/mkdocs-material/) for advanced features
+
+## Code of Conduct
+
+All contributors must adhere to our [Code of Conduct](docs/CODE_OF_CONDUCT.md) and organizational principles of engagement.
+
+---
+
+Thank you for helping improve the Imageomics Guide! Your contributions help make collaborative scientific computing more accessible and effective.

README.md

@@ -2,22 +2,39 @@
 
 Welcome to the Imageomics Guide!
 
-Just joining or starting a new project? 
-Checkout the [Imageomics Guide](https://imageomics.github.io/Imageomics-guide/) for guidance on conventions and best practices.
+Just joining or starting a new project?
+Check out the [Imageomics Guide](https://imageomics.github.io/Imageomics-guide/) for guidance on conventions and best practices.
 
 ## About the Guide
 
-This guide started as an Institute-internal wiki, focused on providing guidance and best practices for collaborative and interdisciplinary (computer science + biology) work. Recognizing that the topics and suggestions are broadly applicable to anyone working in similar or adjacent fields, we moved the vast majority to this [guide](https://imageomics.github.io/Imageomics-guide/). To increase accessibility for those less familiar with GitHub, we generated the [web site](https://imageomics.github.io/Imageomics-guide/) from our Markdown documents (which used to be wiki pages) with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+This guide started as an Imageomics Institute-internal wiki, focused on providing guidance and best practices for collaborative and interdisciplinary (computer science + biology) work. Recognizing that the topics and suggestions are broadly applicable to anyone working in similar or adjacent fields, we moved the vast majority to this [guide](https://imageomics.github.io/Imageomics-guide/). To increase accessibility for those less familiar with GitHub, we generated the website from our Markdown documents (which used to be wiki pages) with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
 
-Please feel free to open an [issue](https://github.com/Imageomics/Imageomics-guide/issues) with any questions regarding the content fo this guide or if you would like to contribute to the [Glossary](https://imageomics.github.io/Imageomics-guide/wiki-guide/Glossary-for-Imageomics/) or [Helpful Tools page](https://imageomics.github.io/Imageomics-guide/wiki-guide/Helpful-Tools-for-your-Workflow/).
+Please feel free to open an [issue](https://github.com/Imageomics/Imageomics-guide/issues) with any questions regarding the content of this guide.
+
+## Contributing
+
+If you'd like to contribute to this guide, please read our [Contributing Guidelines](CONTRIBUTING.md) for information about our standards, development workflow, and submission process.
 
 ### Testing
+
 To test this site locally, first clone this repository, then create an environment with `requirements.txt`
+
 ```
 pip install -r requirements.txt
 ```
+
 and run `mkdocs serve`:
+
 ```
 mkdocs serve
 ```
-Then the site will run at http://127.0.0.1:8000/Imageomics-guide/.
+
+Then the site will run at <http://127.0.0.1:8000/Imageomics-guide/>.
+
+### History
+
+This guide houses the information needed to get started with and use institute resources readily available to all members. However, most of its content is applicable to anyone working more broadly in the field of [_imageomics_](https://imageomics.github.io/Imageomics-guide/wiki-guide/Glossary-for-Imageomics.md/#imageomics) or adjacent fields of computer and data science, and it is tailored to help domain scientists bridging that gap. We further expanded development to include a more general template guide, the [Collaborative Distributed Science Guide](https://imageomics.github.io/Collaborative-distributed-science-guide/), for others wishing to develop a similar organization-specific guide (please see the [template repository](https://github.com/Imageomics/Collaborative-distributed-science-guide) for more information). This solution was born out of the desire to do so for the [AI and Biodiversity Change (ABC) Global Center](http://abcresearchcenter.org) while limiting duplicative updates between guides (Imageomics and ABC share some team members on this project).
+
+## Acknowledgments
+
+This work was supported by both the [Imageomics Institute](https://imageomics.org) and the [AI and Biodiversity Change (ABC) Global Center](http://abcresearchcenter.org). The Imageomics Institute is funded by the US National Science Foundation's Harnessing the Data Revolution (HDR) program under [Award #2118240](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2118240) (Imageomics: A New Frontier of Biological Information Powered by Knowledge-Guided Machine Learning). The ABC Global Climate Center is funded by the US National Science Foundation under [Award No. 2330423](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2330423&HistoricalAwards=false) and Natural Sciences and Engineering Research Council of Canada under [Award No. 585136](https://www.nserc-crsng.gc.ca/ase-oro/Details-Detailles_eng.asp?id=782440). This guide draws on research supported by the Social Sciences and Humanities Research Council. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation, Natural Sciences and Engineering Research Council of Canada, or Social Sciences and Humanities Research Council.

docs/CODE_OF_CONDUCT.md

@@ -6,13 +6,13 @@ To this end, we agree as individuals and as a group to:
 
 - **Listen to understand.** When one person talks, others listen.
 - **Speak to be understood.** We use lay terms and are patient with people who are not experts in our specific field. We are all learning, no matter who we are.
-- Embrace **“Yes and…”** Focus on possibilities instead of obstacles. Be inclusive of other people’s ideas. Honor divergence. 
+- Embrace **“Yes and…”** Focus on possibilities instead of obstacles. Be inclusive of other people’s ideas. Honor divergence.
 - **Take space / make space.** Those who tend to talk a lot are intentional about letting others talk first, while those who tend to hold back are intentional about contributing.
-- **Beware of blind spots.** We do not know what we do not know. We are vigilant for differences among our experiences and positions. 
-- **Respect time.** When a session is over, we need to move on. There is designated time for in-depth follow up and continuing conversations. 
-- **Care** for each other. We bring our full selves to the community, and we look out for each other wholeheartedly. 
+- **Beware of blind spots.** We do not know what we do not know. We are vigilant for differences among our experiences and positions.
+- **Respect time.** When a session is over, we need to move on. There is designated time for in-depth follow up and continuing conversations.
+- **Care** for each other. We bring our full selves to the community, and we look out for each other wholeheartedly.
 
-We abide by these principles in all Imageomics spaces, including but not limited to digital and in-person meetings, formal and informal gatherings, online discussion forums and chat spaces, and field and lab work. 
+We abide by these principles in all Imageomics spaces, including but not limited to digital and in-person meetings, formal and informal gatherings, online discussion forums and chat spaces, and field and lab work.
 
 Acts of misconduct are prohibited. Those found to engage in misconduct will be subject to dismissal from the project and further actions as directed by the guidelines of the employers and the place of incidence.
 
@@ -25,11 +25,19 @@ If you believe you have experienced or witnessed misconduct in an Imageomics set
 Privacy will be protected to the greatest extent possible.
 
 ## VALUES
+
 ### TRANSPARENCY
+
 We ensure our efforts are clear about assumptions, uncertainty, and limits, and provide open sources of information, processes, and discovery.
+
 ### ACCOUNTABILITY
+
 We are responsible, individually and collectively, for the outcomes we produce and ensure, to the best of our abilities, that the methods outcome matches intended use.
+
 ### COLLABORATION
+
 We create and nurture collaborative environments and welcome, value, and affirm all members of our community. We also consider how and for whom solutions are created and promote the heterogeneity of perspectives in the creation process. We actively engage others’ perspectives, recognize everyone’s potential to contribute new ideas, and work together to find creative solutions to complex problems.
+
 ### SAFETY
+
 We ensure our practices are ethical and impartial to the best of our ability. We address ethical issues when we discover them and practice good data governance.  We strive to enhance practices while openly addressing those that harm people or the environment.