diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..0372e10 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,19 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file + +version: 2 +updates: + - package-ecosystem: "docker" + directory: "/" + schedule: + interval: "weekly" + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..b3ef0e4 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,43 @@ +name: build + +on: + pull_request: + branches: + - main + +permissions: + contents: read + pull-requests: write + +jobs: + build-the-book: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - uses: actions/setup-node@v6 + with: + node-version: 18.x + + - name: Install MyST Markdown + run: npm install -g mystmd + + - name: Build HTML Assets + run: myst build --html + + # - name: Deploy to Netlify + # uses: nwtgck/actions-netlify@v3.0 + # with: + # publish-dir: "./_build/html" + # production-branch: main + # github-token: ${{ secrets.GITHUB_TOKEN }} + # deploy-message: "Deploy from GitHub Actions" + # enable-pull-request-comment: true + # enable-commit-comment: false + # overwrites-pull-request-comment: true + # env: + # NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} + # NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..e66fa23 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,54 @@ +name: deploy + +on: + push: + branches: + - main + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + + - name: Setup Pages + uses: actions/configure-pages@v6 + + - uses: actions/setup-node@v6 + with: + node-version: 18.x + + - name: Install MyST Markdown + run: npm install -g mystmd + + - name: Build HTML Assets + run: myst build --html + + # - name: Copy static files + # run: | + # cp robots.txt ./_build/html/ + # # cp CNAME ./_build/html/ + + - name: Upload artifact + uses: actions/upload-pages-artifact@v4 + with: + path: "./_build/html" + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 diff --git a/.gitignore b/.gitignore index b7faf40..de8dda0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ # Byte-compiled / optimized / DLL files __pycache__/ -*.py[codz] +*.py[cod] *$py.class # C extensions @@ -20,15 +20,12 @@ parts/ sdist/ var/ wheels/ -share/python-wheels/ *.egg-info/ .installed.cfg *.egg -MANIFEST +private/ # PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec @@ -49,7 +46,6 @@ coverage.xml *.py.cover .hypothesis/ .pytest_cache/ -cover/ # Translations *.mo @@ -58,8 +54,6 @@ cover/ # Django stuff: *.log local_settings.py -db.sqlite3 -db.sqlite3-journal # Flask stuff: instance/ @@ -72,77 +66,28 @@ instance/ docs/_build/ # PyBuilder -.pybuilder/ target/ # Jupyter Notebook .ipynb_checkpoints -# IPython -profile_default/ -ipython_config.py - # pyenv -# For a library or package, you might want to ignore these files since the code is -# intended to run in multiple environments; otherwise, check them in: -# .python-version - -# pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock - -# UV -# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -#uv.lock - -# poetry -# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control -#poetry.lock -#poetry.toml - -# pdm -# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. -# pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python. -# https://pdm-project.org/en/latest/usage/project/#working-with-version-control -#pdm.lock -#pdm.toml -.pdm-python -.pdm-build/ - -# pixi -# Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control. -#pixi.lock -# Pixi creates a virtual environment in the .pixi directory, just like venv module creates one -# in the .venv directory. It is recommended not to include this directory in version control. -.pixi - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Celery stuff +.python-version + +# celery beat schedule file celerybeat-schedule -celerybeat.pid # SageMath parsed files *.sage.py -# Environments +# dotenv .env -.envrc + +# virtualenv .venv -env/ venv/ +env/ ENV/ -env.bak/ -venv.bak/ # Spyder project settings .spyderproject @@ -156,52 +101,24 @@ venv.bak/ # mypy .mypy_cache/ -.dmypy.json -dmypy.json - -# Pyre type checker -.pyre/ - -# pytype static type analyzer -.pytype/ - -# Cython debug symbols -cython_debug/ - -# PyCharm -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ - -# Abstra -# Abstra is an AI-powered process automation framework. -# Ignore directories containing user credentials, local state, and settings. -# Learn more at https://abstra.io/docs -.abstra/ - -# Visual Studio Code -# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore -# that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore -# and can be added to the global gitignore or merged into this file. However, if you prefer, -# you could uncomment the following to ignore the entire vscode folder -# .vscode/ - -# Ruff stuff: -.ruff_cache/ - -# PyPI configuration file -.pypirc - -# Cursor -# Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to -# exclude from AI features like autocomplete and code analysis. Recommended for sensitive data -# refer to https://docs.cursor.com/context/ignore-files -.cursorignore -.cursorindexingignore - -# Marimo -marimo/_static/ -marimo/_lsp/ -__marimo__/ + +# IDE settings +.vscode/ + +# MyST / Jupyter Book build outputs +_build/ +book-clean/ + +# Translation image directories (images are copied from book/images/ at build time) +book-*/images/ + +# Large data files +*.tif +*.geojson +*.xml +*.gpkg +*.mp4 +*.zip + +# Private / local files +private/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..c5027d9 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,32 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: check-toml + - id: check-yaml + - id: end-of-file-fixer + types: [python] + - id: trailing-whitespace + - id: requirements-txt-fixer + - id: check-added-large-files + args: ["--maxkb=3500"] + + - repo: https://github.com/psf/black + rev: 25.1.0 + hooks: + - id: black-jupyter + + - repo: https://github.com/codespell-project/codespell + rev: v2.4.1 + hooks: + - id: codespell + args: + [ + "--ignore-words-list=previos", + "--skip=*.csv,*.geojson,*.json,*.yml,*.js,*.html,*cff,*.pdf", + ] + + - repo: https://github.com/kynan/nbstripout + rev: 0.8.1 + hooks: + - id: nbstripout diff --git a/CNAME b/CNAME new file mode 100644 index 0000000..26781ab --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +myst-template.opengeos.org diff --git a/CONDUCT.md b/CONDUCT.md new file mode 100644 index 0000000..ae95d60 --- /dev/null +++ b/CONDUCT.md @@ -0,0 +1,40 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the project maintainers. All complaints will be reviewed and +investigated promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.0. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..94397b6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,43 @@ +# Contributing + +Thank you for your interest in contributing to this book project! + +## How to Contribute + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/my-contribution`) +3. Make your changes +4. Run `pre-commit run --all-files` to ensure code quality +5. Commit your changes (`git commit -m 'Add my contribution'`) +6. Push to the branch (`git push origin feature/my-contribution`) +7. Open a Pull Request + +## Development Setup + +1. Clone the repository +2. Install dependencies: `pip install -r requirements.txt` +3. Install pre-commit hooks: `pre-commit install` + +## Building the Book + +### HTML (for web) + +```bash +myst build --html +``` + +### PDF and EPUB (via Typst) + +```bash +python build_translation.py en +``` + +## Code Style + +- Python code follows [Black](https://black.readthedocs.io/) formatting +- Markdown files use [MyST Markdown](https://mystmd.org/) syntax +- All code is spell-checked with [codespell](https://github.com/codespell-project/codespell) + +## Reporting Issues + +Please use the GitHub issue tracker to report bugs or suggest features. diff --git a/LICENSE b/LICENSE index a0705f0..8e06999 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2026 Open Geospatial Solutions +Copyright (c) 2026 Qiusheng Wu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 7b52430..29b6b0e 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,92 @@ -# myst-website-template -A template for MyST websites +# MyST Website Template + +A reusable template for building websites with [MyST Markdown](https://mystmd.org/) and automated deployment via GitHub Actions. + +## Features + +- **MyST Markdown** source format with Jupyter notebook integration +- **GitHub Pages** deployment on push to `main` +- **Netlify PR previews** for pull request review +- **Pre-commit hooks**: Black, codespell, nbstripout for code quality + +## Quick Start + +1. Click **Use this template** on GitHub to create a new repository +2. Update `myst.yml` with your site title, author, and table of contents +3. Replace placeholder content in `book/` with your own pages +4. Push to GitHub to trigger automated builds + +## Project Structure + +``` +. +├── myst.yml # MyST configuration +├── index.md # Landing page +├── requirements.txt # Python dependencies +├── logo.png # Site logo +├── fav.ico # Favicon +├── CNAME # Custom domain (optional) +├── robots.txt # Search engine directives +├── book/ # Site content +│ ├── preface.md +│ ├── part01/ +│ │ ├── getting-started.md +│ │ └── installation.md +│ ├── part02/ +│ │ └── first-example.md +│ ├── references.bib # Bibliography +│ ├── jupytext.toml +│ └── images/ # Shared images +├── .pre-commit-config.yaml # Pre-commit hook configuration +├── CONTRIBUTING.md # Contribution guidelines +├── CONDUCT.md # Code of conduct +└── .github/workflows/ + ├── build.yml # PR preview builds (Netlify) + └── deploy.yml # Production deployment (GitHub Pages) +``` + +## Customization + +### Site Metadata + +Edit `myst.yml`: +- `project.title`: your site title +- `project.authors`: author name(s) +- `project.github`: your GitHub `username/repo` +- `project.toc`: table of contents structure + +### Adding Pages + +1. Create a new `.md` file in the appropriate `book/` subdirectory +2. Add the file to `project.toc` in `myst.yml` + +## Building Locally + +```bash +pip install -r requirements.txt +npm install -g mystmd +myst build --html +``` + +The built site will be in `_build/html/`. + +## Deployment + +### GitHub Pages (production) + +Pushes to `main` automatically trigger the `deploy.yml` workflow, which builds the HTML site and deploys to GitHub Pages. + +### Netlify (PR previews) + +Pull requests trigger the `build.yml` workflow, which builds a preview and posts the URL as a PR comment. Requires `NETLIFY_AUTH_TOKEN` and `NETLIFY_SITE_ID` secrets. + +## GitHub Secrets + +| Secret | Purpose | +|--------|---------| +| `NETLIFY_AUTH_TOKEN` | Netlify authentication for PR previews | +| `NETLIFY_SITE_ID` | Netlify site ID for PR previews | + +## License + +[MIT](LICENSE) diff --git a/book/images/.gitkeep b/book/images/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/book/images/sample_figure.png b/book/images/sample_figure.png new file mode 100644 index 0000000..79abdb4 Binary files /dev/null and b/book/images/sample_figure.png differ diff --git a/book/jupytext.toml b/book/jupytext.toml new file mode 100644 index 0000000..7db2243 --- /dev/null +++ b/book/jupytext.toml @@ -0,0 +1,9 @@ +# Install jupytext using: conda install jupytext -c conda-forge +# Always pair ipynb notebooks to md files. +# formats = "ipynb,md" +formats = "ipynb,myst" + +# jupytext --to ipynb *.md # convert all .md files to notebooks with no outputs +# jupytext --to ipynb --execute *.md # convert all .md files to notebooks and execute them +# jupytext --set-formats ipynb,md --execute *.md # convert all .md files to paired notebooks and execute them +# jupytext --to md *.ipynb # convert all .ipynb files to .md files diff --git a/book/part01/getting-started.md b/book/part01/getting-started.md new file mode 100644 index 0000000..cec9025 --- /dev/null +++ b/book/part01/getting-started.md @@ -0,0 +1,60 @@ +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 +kernelspec: + display_name: Python 3 + language: python + name: python3 +title: Getting Started +abstract: "" +authors: + - name: Author Name +exports: + - format: typst + template: lapreprint-typst + output: _build/exports/typst/ +--- + +# Getting Started + +This chapter introduces the fundamental concepts. + +## Overview + +Provide an overview of the topic here. + +## Key Concepts + +Explain the key concepts that readers need to understand. + +```{code-cell} ipython3 +print("Hello, World!") +``` + +## Sample Table + +The table below shows an overview of the key tools used in this book. + +```{list-table} Overview of key tools +:header-rows: 1 +:name: tab-tools + +* - Tool + - Description + - Version +* - Python + - Programming language + - 3.12 +* - NumPy + - Numerical computing library + - 1.26 +* - Matplotlib + - Plotting and visualization + - 3.8 +* - MyST + - Markdown authoring framework + - 1.8 +``` diff --git a/book/part01/installation.md b/book/part01/installation.md new file mode 100644 index 0000000..4337c74 --- /dev/null +++ b/book/part01/installation.md @@ -0,0 +1,40 @@ +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 +kernelspec: + display_name: Python 3 + language: python + name: python3 +title: Installation +abstract: "" +authors: + - name: Author Name +exports: + - format: typst + template: lapreprint-typst + output: _build/exports/typst/ +--- + +# Installation + +This chapter covers how to set up your environment. + +## Prerequisites + +List the prerequisites here. + +## Installation Steps + +```bash +pip install numpy matplotlib +``` + +## Verifying the Installation + +```{code-cell} ipython3 +import sys +print(f"Python version: {sys.version}") +``` diff --git a/book/part02/first-example.md b/book/part02/first-example.md new file mode 100644 index 0000000..fa9354b --- /dev/null +++ b/book/part02/first-example.md @@ -0,0 +1,59 @@ +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 +kernelspec: + display_name: Python 3 + language: python + name: python3 +title: First Example +abstract: "" +authors: + - name: Author Name +exports: + - format: typst + template: lapreprint-typst + output: _build/exports/typst/ +--- + +# First Example + +This chapter walks through a complete example. + +## Setting Up + +Describe the setup steps here. + +## Sample Figure + +{numref}`fig-sample` shows a sample bar chart generated with Matplotlib. + +```{figure} ../images/sample_figure.png +:name: fig-sample +:alt: A sample bar chart + +A sample bar chart showing values for five categories. +``` + +## Running the Example + +```{code-cell} ipython3 +import numpy as np +import matplotlib.pyplot as plt + +x = np.linspace(0, 2 * np.pi, 100) +y = np.sin(x) + +fig, ax = plt.subplots() +ax.plot(x, y) +ax.set_xlabel("x") +ax.set_ylabel("sin(x)") +ax.set_title("A Simple Plot") +plt.show() +``` + +## Summary + +This example demonstrated the basic workflow. diff --git a/book/preface.md b/book/preface.md new file mode 100644 index 0000000..d83e206 --- /dev/null +++ b/book/preface.md @@ -0,0 +1,35 @@ +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 +kernelspec: + display_name: Python 3 + language: python + name: python3 +title: Preface +abstract: "" +authors: + - name: Author Name +exports: + - format: typst + template: lapreprint-typst + output: _build/exports/typst/ +--- + +# Preface + +Welcome to this book. This preface provides an overview of what you will learn. + +## Who This Book Is For + +This book is for anyone interested in the topic. + +## How to Use This Book + +Each chapter builds on the previous one. Start from the beginning and work your way through. + +## Acknowledgements + +Thank you to everyone who contributed to this book. diff --git a/book/references.bib b/book/references.bib new file mode 100644 index 0000000..f883f8d --- /dev/null +++ b/book/references.bib @@ -0,0 +1,6 @@ +@book{example2026, + title = {Example Website Title}, + author = {Author, Example}, + year = {2026}, + publisher = {Publisher Name} +} diff --git a/fav.ico b/fav.ico new file mode 100644 index 0000000..5e7b707 Binary files /dev/null and b/fav.ico differ diff --git a/index.md b/index.md new file mode 100644 index 0000000..fe0f567 --- /dev/null +++ b/index.md @@ -0,0 +1,32 @@ +# Website Title + +## Introduction + +Welcome to the official repository for _**Website Title**_. This repository contains all the code examples featured in the book. + +## About This Book + +Describe your book here. + +## Table of Contents + +### Preface + +- [Preface](book/preface.md) + +### Part I: Getting Started + +1. [Getting Started](book/part01/getting-started.md) +2. [Installation](book/part01/installation.md) + +### Part II: Examples + +3. [First Example](book/part02/first-example.md) + +## About the Author + +Add author information here. + +## Licensing and Copyright + +Add licensing information here. diff --git a/logo.png b/logo.png new file mode 100644 index 0000000..031c2f3 Binary files /dev/null and b/logo.png differ diff --git a/myst.yml b/myst.yml new file mode 100644 index 0000000..57701f0 --- /dev/null +++ b/myst.yml @@ -0,0 +1,43 @@ +version: 1 +project: + title: Website Title + authors: + - name: Author Name + copyright: '2026' + exclude: + - _build + - Thumbs.db + - .DS_Store + - '**.ipynb_checkpoints' + github: username/book-template + # thebe: + # binder: + # repo: username/book-template + # provider: github + # url: https://mybinder.org + # ref: main + bibliography: + - book/references.bib + toc: + - file: index.md + - title: Preface + children: + - file: book/preface.md + - title: Getting Started + children: + - file: book/part01/getting-started.md + - file: book/part01/installation.md + - title: Examples + children: + - file: book/part02/first-example.md +site: + options: + logo: logo.png + logo_dark: logo.png + favicon: fav.ico + folders: true + # style: custom.css + # analytics_google: G-XXX + template: book-theme + parts: + primary_sidebar_footer: '' diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..b2e0cc2 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,6 @@ +ghp-import +jupyter-book +jupytext +matplotlib +mystmd +numpy diff --git a/robots.txt b/robots.txt new file mode 100644 index 0000000..1f53798 --- /dev/null +++ b/robots.txt @@ -0,0 +1,2 @@ +User-agent: * +Disallow: /