|
| 1 | +# Discovery — Authoring Tutorial & Formatting Tips |
| 2 | + |
| 3 | +This document is a short tutorial that walks you through creating a new Discovery post (Markdown) and the formatting best-practices we use on the site. |
| 4 | + |
| 5 | +Quick summary |
| 6 | + |
| 7 | +- Files live in: `content/discovery/` (one Markdown file per post) |
| 8 | +- Images/assets live in: `public/discovery/<slug>/` |
| 9 | +- Build-time RSS: `public/discovery/rss.xml` (generated at build time) |
| 10 | + |
| 11 | +## Create a new post (quick start) |
| 12 | + |
| 13 | +1. Create the Markdown file. Use a lowercase, hyphenated slug for the filename. |
| 14 | + |
| 15 | +```bash |
| 16 | +mkdir -p content/discovery/my-project |
| 17 | +code content/discovery/my-project/index.md |
| 18 | +``` |
| 19 | + |
| 20 | +1. Add frontmatter (required fields shown) at the top of the file: |
| 21 | + |
| 22 | +```yaml |
| 23 | +--- |
| 24 | +title: "My Project" |
| 25 | +slug: "my-project" # optional (defaults to filename) |
| 26 | +tags: ["utility","map"] |
| 27 | +description: "One-line summary used in the listing and RSS" |
| 28 | +date: "2025-10-08" # ISO YYYY-MM-DD |
| 29 | +image: "/discovery/my-project/hero.png" |
| 30 | +download: "https://cdn.example.com/my-project/my-project.zip" |
| 31 | +--- |
| 32 | +``` |
| 33 | + |
| 34 | +1. Add Markdown content below the frontmatter. Use H2/H3 headings for structure (avoid H1 in the body because the post title is the page H1). |
| 35 | + |
| 36 | +Minimal file example: |
| 37 | + |
| 38 | +Frontmatter (top of the file): |
| 39 | + |
| 40 | +```yaml |
| 41 | +--- |
| 42 | +title: "My Project" |
| 43 | +description: "Short summary for listing" |
| 44 | +date: "2025-10-08" |
| 45 | +image: "/discovery/my-project/hero.png" |
| 46 | +--- |
| 47 | +``` |
| 48 | + |
| 49 | +Content skeleton (add below the frontmatter): |
| 50 | + |
| 51 | +## Overview |
| 52 | + |
| 53 | +Short intro paragraph used as the listing summary. |
| 54 | + |
| 55 | +## Installation |
| 56 | + |
| 57 | +Instructions, code block (add language): |
| 58 | + |
| 59 | +```bash |
| 60 | +curl -L -o myproject.zip https://cdn.example.com/myproject.zip |
| 61 | +``` |
| 62 | + |
| 63 | +## Usage |
| 64 | + |
| 65 | +Explain how to use the project, include screenshots with alt text: |
| 66 | + |
| 67 | + |
| 68 | + |
| 69 | +Formatting & styling tips |
| 70 | + |
| 71 | +- Headings: |
| 72 | + - Use H2 (`##`) for section titles and H3 (`###`) for subsections. Do NOT add another H1 — the site's title comes from the post frontmatter. |
| 73 | +- Lists: |
| 74 | + - Use bulleted lists (`-` or `*`) for short item lists. For numbered steps use `1.`. |
| 75 | +- Code blocks: |
| 76 | + - Always include a language for fenced code blocks (e.g. `bash`, `ts`, `json`) so syntax highlighting works. |
| 77 | +- Images: |
| 78 | + - Store images under `public/discovery/<slug>/` and reference them with absolute paths (e.g., `/discovery/my-project/hero.png`). |
| 79 | + - Recommended sizes: hero image ~1200×600 px (or 3:2), thumbnails ~600×400. Use compressed web-friendly formats (WebP/PNG/JPEG). |
| 80 | + - Always include descriptive `alt` text for accessibility and SEO. |
| 81 | +- Links & downloads: |
| 82 | + - For paid or large files host externally (S3, CDN, Gumroad). Put the public URL in the frontmatter `download:` field. |
| 83 | + - For small free samples you may put a small archive under `public/discovery/<slug>/` and link to it from the body or frontmatter. |
| 84 | + |
| 85 | +## Downloads in frontmatter |
| 86 | + |
| 87 | + You can include download URLs in a post's frontmatter. Two formats are supported: |
| 88 | + |
| 89 | + 1. Legacy single-download string: |
| 90 | + |
| 91 | + ```yaml |
| 92 | + download: "https://example.com/files/my-addon-v1.0.mcpack" |
| 93 | + ``` |
| 94 | + |
| 95 | + 1. Multiple-downloads array (recommended) — allows labeling versions and adding notes: |
| 96 | + |
| 97 | + ```yaml |
| 98 | + downloads: |
| 99 | + - label: "Release v1.2" |
| 100 | + url: "https://cdn.example.com/tcvm/v1.2/tcvm.mcpack" |
| 101 | + notes: "Stable release — recommended" |
| 102 | + - label: "Beta v1.3-beta" |
| 103 | + url: "https://cdn.example.com/tcvm/v1.3-beta/tcvm-modded.mcpack" |
| 104 | + notes: "Beta — may be unstable" |
| 105 | + ``` |
| 106 | + |
| 107 | + Buttons for each download will be rendered on the post page. For large or paid downloads, host files on an external CDN or filesharing service and add the external URL in the frontmatter to avoid committing binaries to the repository. |
| 108 | + |
| 109 | +- Table of contents and heading anchors |
| 110 | + |
| 111 | +- We inject `id` attributes for H2–H6 headings automatically, so linking to `#your-heading` in the page will work. |
| 112 | +- If you want a TOC, place an explicit list at the top of the document. We render a `prose` style; you can add a small `.toc` wrapper if you want custom styling. |
| 113 | + |
| 114 | +Preview & RSS |
| 115 | + |
| 116 | +- Local preview: `npm run dev` and browse `http://localhost:3000/discovery`. |
| 117 | +- Build-time RSS: `getStaticProps` generates `public/discovery/rss.xml` during `next build`. To regenerate the feed, run: |
| 118 | + |
| 119 | +```bash |
| 120 | +npm run build |
| 121 | +``` |
| 122 | + |
| 123 | +Accessibility & SEO tips |
| 124 | + |
| 125 | +- Keep the `description` short (1–2 sentences) — it’s used for RSS and card summaries. |
| 126 | +- Use complete sentences, include descriptive alt text for images, and prefer semantic headings (H2/H3). |
| 127 | + |
| 128 | +Common troubleshooting |
| 129 | + |
| 130 | +- Images 404: ensure images are placed under `public/discovery/<slug>/` and that your `image` frontmatter path matches exactly. |
| 131 | +- Linter warnings: |
| 132 | + - MD025: avoid adding a second H1; remove H1 from the body. |
| 133 | + - MD033: the linter flags raw HTML inside Markdown — the README allows a small wrapper div for TOC but you can avoid inline HTML if you prefer. |
| 134 | +- Styles not applying: ensure Tailwind's typography plugin is installed and the page uses `prose` or `prose-invert` for dark theme. |
| 135 | + |
| 136 | +Developer commands (quick) |
| 137 | + |
| 138 | +```bash |
| 139 | +# scaffold a new post folder |
| 140 | +mkdir -p public/discovery/my-project && mkdir -p content/discovery/my-project |
| 141 | +cp path/to/image.png public/discovery/my-project/hero.png |
| 142 | +code content/discovery/my-project/index.md |
| 143 | + |
| 144 | +# regenerate RSS (build) |
| 145 | +npm run build |
| 146 | +``` |
| 147 | + |
| 148 | +Finish & tips |
| 149 | + |
| 150 | +- Keep entries focused and short; the site shows a short description and thumbnails on the index page. Use the body for details, screenshots, and instructions. |
| 151 | +- When ready to publish, verify the post preview under `npm run dev`, then commit the `content/discovery/<slug>.md` and any small images under `public/discovery/<slug>/`. |
| 152 | + |
0 commit comments