diff --git a/app/assets/icons/.gitkeep b/app/assets/icons/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/install.md b/docs/install.md index 4806565..519af3a 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,169 +1,3 @@ -# Setting up mdcms for your site +# Folder title -This guide walks through installing mdcms, registering your site, and setting up automatic builds on GitHub so that `nav.yml` and `search.json` are always up to date when you push content. - -## 1. Install mdcms - -Choose one method: - -**Standalone binary (no Python required — recommended for most users)** - -Download the binary for your platform from the [latest release](https://github.com/kbenestad/mdcms/releases/latest): - -- **Linux:** `mdcms-linux-amd64` → move to `/usr/local/bin/mdcms` and `chmod +x` -- **Linux (deb):** `mdcms__amd64.deb` → `sudo dpkg -i mdcms__amd64.deb` -- **macOS:** `mdcms-macos-arm64` → move to `/usr/local/bin/mdcms` and `chmod +x` -- **Windows:** `mdcms-windows-amd64.exe` → rename to `mdcms.exe` and place it somewhere on your PATH - -**Via pip (from GitHub)** -```bash -pip install git+https://github.com/kbenestad/mdcms.git -``` - -**Via pipx (from GitHub)** -```bash -pipx install git+https://github.com/kbenestad/mdcms.git -``` - -Verify the installation: -```bash -mdcms --version -``` - ---- - -## 2. Register your site - -Navigate to your site directory (where `index.html` lives) and register it: - -```bash -cd /path/to/your/site -mdcms register mysite -``` - -Or pass the path explicitly: -```bash -mdcms register mysite /path/to/your/site -``` - -**If no mdcms site exists at that path**, mdcms will download the starter template from GitHub automatically — `index.html`, `config.yml`, `pages/`, `posts/`, and `assets/` will be created for you. - -**If a site already exists** (you cloned an existing mdcms repo), mdcms will detect the version marker in `config.yml` and register it as-is. - ---- - -## 3. Edit your config - -Open `config.yml` in your site directory and set at minimum: - -```yaml -sitename: Your Site Name -navigation: topbar # or: sidebar -``` - ---- - -## 4. Build locally - -Run a build to generate `nav.yml` and `search.json` from your content: - -```bash -mdcms build mysite -``` - -Check your site by starting a local server: -```bash -cd /path/to/your/site -python3 -m http.server 8800 -``` - -Then open `http://localhost:8800` in your browser. - ---- - -## 5. Set up automatic builds on GitHub - -When you push new pages or posts to GitHub, you'll want `nav.yml` and `search.json` rebuilt automatically. This is done with a simple GitHub Actions workflow. - -### One-time GitHub setup - -1. Go to your site repository on GitHub -2. **Settings → Actions → General** -3. Under **Workflow permissions**, select **Read and write permissions** -4. Click **Save** - -This allows the workflow to commit the rebuilt files back to your repository. - -### Add the workflow file - -Create `.github/workflows/build.yml` in your site repository with this content: - -```yaml -name: Build - -on: - push: - branches: - - main - paths: - - "pages/**" - - "posts/**" - - "config.yml" - -env: - FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - - name: Install mdcms - run: pip install git+https://github.com/kbenestad/mdcms.git - - - name: Build - run: mdcms build - - - name: Commit updated files - run: | - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - git add nav.yml search.json - git diff --staged --quiet || git commit -m "Build: update nav.yml and search.json" - git push -``` - -Commit and push this file to your repository. From that point on, every push that touches `pages/`, `posts/`, or `config.yml` will automatically rebuild and commit `nav.yml` and `search.json`. - -> The workflow only commits if the files actually changed — `git diff --staged --quiet` skips the commit if nothing is different. - ---- - -## Day-to-day workflow - -1. Write or edit a page in `pages/` or a post in `posts/` -2. Commit and push to `main` -3. GitHub Actions rebuilds `nav.yml` and `search.json` automatically (~30 seconds) -4. Your deployed site picks up the changes immediately - -To build locally at any time (without pushing): -```bash -mdcms build mysite -``` - ---- - -## Useful commands - -```bash -mdcms view # list all registered sites -mdcms view mysite # show details for a site -mdcms build mysite # build nav.yml + search.json -mdcms build --path . # build from current directory (no registry needed) -mdcms delete mysite # remove a site from the local registry -``` +A **README.md** is a Markdown file with its content prominently displayed on top of the folder in Nextcloud. \ No newline at end of file diff --git a/latest/linux/mdcms b/latest/linux/mdcms index 7d8ca84..4ae4271 100644 Binary files a/latest/linux/mdcms and b/latest/linux/mdcms differ diff --git a/latest/linux/mdcms.deb b/latest/linux/mdcms.deb new file mode 100644 index 0000000..0bf0c71 Binary files /dev/null and b/latest/linux/mdcms.deb differ diff --git a/latest/macos/mdcms b/latest/macos/mdcms index 4617c8a..afd4c2b 100644 Binary files a/latest/macos/mdcms and b/latest/macos/mdcms differ diff --git a/latest/windows/mdcms.exe b/latest/windows/mdcms.exe index c8df349..3538e4f 100644 Binary files a/latest/windows/mdcms.exe and b/latest/windows/mdcms.exe differ