Working with Images
Images enhance documentation by providing visual context, examples, and breaking up text-heavy content. Here’s how to use them effectively in CelestialDocs.
Image Storage Locations
Content Collection Assets (Recommended)
Store images alongside your documentation in content/docs/assets/:
content/
└── docs/
├── assets/
│ ├── getting-started.jpg
│ ├── configuration-overview.jpg
│ └── navigation-hierarchy.jpg
├── getting-started/
│ └── setup.mdx
└── configuration/
└── basics/
└── overview.mdxBenefits:
- Images live with documentation content
- Easy to version control together
- Better organization for multiple collections
- Clear scope and ownership
Public Folder (Site-wide Assets)
Use public/ for assets shared across all collections:
public/
├── logo.svg
├── favicon.ico
└── shared-diagram.pngUse cases:
- Logo and branding assets
- Favicons and meta images
- Shared diagrams used in multiple collections
Using Images in Markdown
Basic Syntax
Relative Paths from Content
Images in the same collection use relative paths:
<!-- From content/docs/getting-started/setup.mdx -->
<!-- From content/docs/configuration/basics/overview.mdx -->
Example with Images
The image above demonstrates configuration concepts visually.
Image Best Practices
1. Descriptive Alt Text
Always provide meaningful alt text for accessibility:
<!-- ❌ Bad -->
<!-- ✅ Good -->
2. Optimize File Sizes
- Hero images: 1200x630px, ~100KB max
- Content images: 800x400px, ~50KB max
- Screenshots: Actual size, compressed
- Format: WebP (best), JPEG (good), PNG (when transparency needed)
3. Naming Conventions
Use descriptive, kebab-case names:
✅ navigation-hierarchy-diagram.jpg
✅ getting-started-hero.jpg
✅ config-example-screenshot.png
❌ img1.jpg
❌ Screen Shot 2024-01-01.png
❌ MyImage.JPG4. Image Dimensions
Consistent sizing creates better visual flow:
<!-- Hero images at top of pages -->
<!-- Inline content images -->
<!-- Small icons or badges -->
Advanced Techniques
Captioned Images
Add context with text below images:
_Figure 1: CelestialDocs navigation architecture showing the three-tier hierarchy_Example:
Figure: Modern development environment with proper tooling
Linking Images
Make images clickable:
[](/docs/configuration/basics/overview)Image in Lists
1. **Setup your environment**
Install Node.js and clone the repository.
2. **Configure settings**
Update data/config.ts with your preferences.Organization Tips
Group by Section
content/docs/assets/
├── getting-started/
│ ├── installation-step-1.jpg
│ └── installation-step-2.jpg
├── configuration/
│ ├── basic-setup.jpg
│ └── advanced-options.jpg
└── shared/
└── logo.svgVersion Images with Docs
When updating documentation, update related images in the same commit:
git add content/docs/getting-started/setup.mdx
git add content/docs/assets/getting-started.jpg
git commit -m "Update setup guide and screenshot"Use .gitattributes for LFS
For large images, consider Git LFS:
*.jpg filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.webp filter=lfs diff=lfs merge=lfs -textTroubleshooting
Image Not Showing
- Check the relative path is correct
- Verify file exists in the assets folder
- Check file extension matches (case-sensitive)
- Ensure image is committed to repository
Path Examples by Location
<!-- From: content/docs/introduction.mdx -->
<!-- From: content/docs/getting-started/setup.mdx -->
<!-- From: content/docs/configuration/basics/overview.mdx -->
<!-- From: content/docs/navigation-system/core-concepts/entries.mdx -->
Build Errors
If images cause build errors:
- Ensure filenames have no spaces
- Use only alphanumeric, hyphens, and underscores
- Check file permissions are correct
- Verify image files aren’t corrupted
Summary
- ✅ Store images in
content/docs/assets/for better organization - ✅ Use descriptive alt text for accessibility
- ✅ Optimize images before adding (WebP or compressed JPEG)
- ✅ Use relative paths from your markdown files
- ✅ Follow consistent naming conventions
- ✅ Keep image sizes appropriate (1200x630 for heroes, 800x400 for content)
Next Steps
- Learn about MDX components for advanced image handling
- Explore Markdown basics for other syntax
- Review Frontmatter options for page configuration