first stab at mkdocs migration

README.md

@@ -1,74 +1,50 @@
 # HPCE Documentation
 
-This site contains internal documentation of HCPE services at Paul Scherrer Institute, particularly the *Merlin 6* and *Merlin 7* clusters.
-Live pages are available at <https://hpce.pages.psi.ch>.
+This site contains internal documentation of HCPE services at Paul Scherrer
+Institute, particularly the *Merlin 6* and *Merlin 7* clusters.  Live pages are
+available at <https://hpce.pages.psi.ch>.
 
-## Installation
+## Development
 
-### Docker
+### Using Docker Compose (Recommended)
 
-The easiest and most reproducable way to test changes is using docker.
-From the top directory, run the following:
+```bash
+# Start the development server
+docker compose up
 
-```console
-$ docker compose build
-$ docker compose up
+# Or run in background
+docker compose up -d
 ```
 
-This will start a webserver on `http://0.0.0.0:4001/`. Changes to most pages
-will be automatically reflected in the website (with the exception of changes
-to `config.yml`, which requires restarting the webserver).
+The documentation will be available at `http://localhost:8000`.
 
-### Running locally
+> [!NOTE]
+> We use several MkDocs plugins, which need to be installed by hand. We do this by
+> using a Dockerfile that pulls in the `squidfunk/mkdocs-material` image and runs
+> some `pip install` commands. This means that on the first `compose up` call, a
+> new docker image will be built locally on your machine.
 
-Building locally requires ruby 2.5 and bundler. To install:
+### Deployment
 
-```console
-$ gem install bundler jekyll
-$ bundle
-```
+The site is automatically deployed to `https://hpce.pages.psi.ch/` via Gitea Pages.
 
-To run a local webserver:
+## Contributing
 
-```console
-$ bundle exec jekyll serve
-```
+Please follow established conventions when adding new documentation:
 
-## Theme
+1. Use clear, descriptive filenames
+2. Follow the existing directory structure
+3. Include appropriate metadata in frontmatter
+4. Test locally before committing
 
-The theme is derived from the
-[Jekyll Doc Theme 6.0](https://github.com/tomjoht/documentation-theme-jekyll)
-by Tom Johnson.
+## Repository Structure
 
-### Organization
+TBD
 
-- Documentation is organized within the `pages` directory
-- Add the following frontmatter to each (Merlin6) page:
+## Contact
 
-  ```md
-  ---
-  title: Introduction
-  sidebar: merlin6_sidebar
-  permalink: /merlin6/introduction.html
-  keywords: key1, key2
-  ---
-  ```
-
-- Sidebars are specified in data files, e.g. `_data/sidebars/merlin6_sidebar.yml`.
-- The top menu is controlled by `_data/topnav.yml`
-- News can be addin in `_posts`. Filenames must include the date.
-- Lots of features still need to be configured (e.g. pdf output, tags, etc)
-- The search bar uses finds substring of the title, tags, keywords, and summary frontmatter.
-
-## Deployment
-
-We use the Gitea workflow (see `.gitea/workflow/deploy-pages.yml` for details). The
-pages are automatically re-generated on each push to `master` branch. The resulting website
-is stored under the `gitea-pages` branch, and is automatically exposed.
+For questions or issues with this documentation, contact the HPCE team.
 
 ## License
 
 Theme content is licensed under the MIT license.
-The Navgoco jQuery component used in the sidebar is licensed under the BSD
-license.
-See licenses subdirectory for license terms.