Skip to content

README.md

Latest commit

 

History

History
86 lines (65 loc) · 3.04 KB

README.md

File metadata and controls

86 lines (65 loc) · 3.04 KB

XMapTools Documentation

Official documentation for XMapTools, a free and versatile software solution for quantitative compositional mapping and analysis. This site is built with VitePress and deployed via GitHub Pages.

Live site: https://xmaptools.github.io/Documentation/

Contributing

Contributions to improve or extend the documentation are welcome. Please follow the workflow described below.

Prerequisites

  • Node.js (v18 or later recommended)
  • Git
  • A GitHub account

Setting Up the Project Locally

  1. Fork this repository on GitHub.
  2. Clone your fork: 
    git clone https://github.com/<your-username>/Documentation.git
cd Documentation
  3. Install dependencies: 
    npm install
  4. Start the local development server: 
    npm run dev
    The site will be available at http://localhost:5173/Documentation/. Changes to .md files are reflected live in the browser.

Writing and Editing Content

  • All documentation pages are written in Markdown (.md files) at the root of the repository.
  • VitePress supports standard Markdown syntax plus additional features such as custom containers, code highlighting, and frontmatter.
  • Images are hosted in the separate Documentation_Images repository. Reference them using raw GitHub URLs with an HTML <img> tag: 
    <img src="https://raw.githubusercontent.com/xmaptools/Documentation_Images/main/Figures/my-image.png" alt="description" style="max-width: 100%; height: auto; display: block; margin: 0 auto;">
  • Navigation and sidebar links are configured in .vitepress/config.js.

Submitting Changes

  1. Create a new branch for your changes: 
    git checkout -b my-contribution
  2. Make your edits and verify them locally with npm run dev.
  3. Commit your changes with a clear message: 
    git add .
git commit -m "docs: describe your changes"
  4. Push to your fork: 
    git push origin my-contribution
  5. Open a Pull Request against the main branch of this repository.
  6. Wait for review and approval before merging.

Style Guidelines

  • Use clear, concise language.
  • Use headings (##, ###) to structure content logically.
  • Prefer numbered lists for sequential instructions and bullet points for unordered items.
  • Include screenshots or diagrams where they help clarify a concept.
  • Keep filenames lowercase with underscores (e.g., installation_guide.md).

Building for Production

npm run build

The static site is generated in .vitepress/dist/ and automatically deployed to GitHub Pages via the CI workflow on push to main.

License

This project is licensed under the GNU General Public License v3.0.