|
1 | 1 | # Kalco Documentation |
2 | 2 |
|
3 | | -This directory contains the documentation website for Kalco, built with the [Just the Docs](https://just-the-docs.github.io/) Jekyll theme. |
| 3 | +This directory contains the documentation for Kalco, built using the [Just the Docs](https://just-the-docs.github.io/just-the-docs/) Jekyll theme. |
4 | 4 |
|
5 | | -## Structure |
| 5 | +## 🏗️ Structure |
6 | 6 |
|
7 | | -- `index.md` - Main landing page |
8 | | -- `docs/` - Documentation pages organized by topic |
9 | | -- `_config.yml` - Jekyll configuration |
10 | | -- `Gemfile` - Ruby dependencies |
| 7 | +``` |
| 8 | +docs/ |
| 9 | +├── _config.yml # Jekyll configuration |
| 10 | +├── Gemfile # Ruby dependencies |
| 11 | +├── index.md # Home page |
| 12 | +├── docs/ # Documentation pages |
| 13 | +│ ├── getting-started/ # Getting started guides |
| 14 | +│ │ ├── index.md # Overview |
| 15 | +│ │ ├── installation.md # Installation guide |
| 16 | +│ │ ├── first-run.md # First run guide |
| 17 | +│ │ └── configuration.md # Configuration guide |
| 18 | +│ └── commands/ # Command reference |
| 19 | +│ ├── index.md # Commands overview |
| 20 | +│ └── export.md # Export command docs |
| 21 | +└── README.md # This file |
| 22 | +``` |
11 | 23 |
|
12 | | -## Features |
| 24 | +## 🚀 Local Development |
13 | 25 |
|
14 | | -- **Search** - Full-text search across all documentation |
15 | | -- **Navigation** - Hierarchical navigation with sidebar |
16 | | -- **Responsive** - Mobile-friendly design |
17 | | -- **GitHub Pages** - Automatic deployment |
18 | | -- **Callouts** - Highlighted information boxes |
19 | | -- **Code Highlighting** - Syntax highlighting for code blocks |
20 | | - |
21 | | -## Local Development |
| 26 | +### Prerequisites |
22 | 27 |
|
23 | | -To run the documentation locally: |
| 28 | +- Ruby 3.0+ (recommended: use Homebrew on macOS) |
| 29 | +- Bundler gem |
24 | 30 |
|
25 | | -1. **Install Ruby and Bundler** |
26 | | - ```bash |
27 | | - # macOS (with Homebrew) |
28 | | - brew install ruby |
29 | | - |
30 | | - # Ubuntu/Debian |
31 | | - sudo apt-get install ruby-full build-essential |
32 | | - |
33 | | - # Install Bundler |
34 | | - gem install bundler |
35 | | - ``` |
| 31 | +### Setup |
36 | 32 |
|
37 | | -2. **Install Dependencies** |
| 33 | +1. **Install Ruby dependencies:** |
38 | 34 | ```bash |
39 | 35 | cd docs |
40 | 36 | bundle install |
41 | 37 | ``` |
42 | 38 |
|
43 | | -3. **Run Locally** |
| 39 | +2. **Start local server:** |
44 | 40 | ```bash |
45 | | - bundle exec jekyll serve |
| 41 | + bundle exec jekyll serve --host 0.0.0.0 --port 4000 |
46 | 42 | ``` |
47 | 43 |
|
48 | | -4. **View Site** |
| 44 | +3. **View site:** |
49 | 45 | Open [http://localhost:4000](http://localhost:4000) in your browser |
50 | 46 |
|
51 | | -## GitHub Pages |
| 47 | +### Build for Production |
| 48 | + |
| 49 | +```bash |
| 50 | +bundle exec jekyll build |
| 51 | +``` |
52 | 52 |
|
53 | | -The documentation is automatically deployed to GitHub Pages when pushed to the main branch. The workflow is defined in `.github/workflows/pages.yml`. |
| 53 | +## 🎨 Theme Features |
54 | 54 |
|
55 | | -## Adding New Pages |
| 55 | +- **Responsive design** - Works on all devices |
| 56 | +- **Search functionality** - Full-text search across all content |
| 57 | +- **Dark/light mode** - Toggle between color schemes |
| 58 | +- **Navigation** - Sidebar navigation with breadcrumbs |
| 59 | +- **Callouts** - Highlighted information boxes |
| 60 | +- **Git integration** - Last modified timestamps |
56 | 61 |
|
57 | | -1. **Create Markdown File** |
58 | | - - Use `.md` extension |
59 | | - - Include front matter with title and navigation order |
| 62 | +## 📝 Adding Content |
60 | 63 |
|
61 | | -2. **Front Matter Example** |
| 64 | +### New Pages |
| 65 | + |
| 66 | +1. Create a new `.md` file in the appropriate directory |
| 67 | +2. Add front matter with metadata: |
62 | 68 | ```yaml |
63 | 69 | --- |
64 | 70 | layout: default |
65 | 71 | title: Page Title |
66 | | - parent: Parent Section |
67 | 72 | nav_order: 1 |
| 73 | + parent: Parent Page |
68 | 74 | --- |
69 | 75 | ``` |
70 | 76 |
|
71 | | -3. **Navigation Structure** |
72 | | - - Use `has_children: true` for parent pages |
73 | | - - Use `parent:` to specify hierarchy |
74 | | - - Use `nav_order:` for ordering |
| 77 | +3. Update navigation by setting `nav_order` values |
| 78 | + |
| 79 | +### Navigation Structure |
| 80 | + |
| 81 | +- Use `nav_order` to control page order |
| 82 | +- Use `parent` to create hierarchical navigation |
| 83 | +- Use `has_children: true` for pages with sub-pages |
| 84 | + |
| 85 | +## 🔧 Configuration |
| 86 | + |
| 87 | +The `_config.yml` file contains: |
| 88 | +- Site metadata (title, description, URL) |
| 89 | +- Just the Docs theme configuration |
| 90 | +- Jekyll build settings |
| 91 | +- Collections and defaults |
75 | 92 |
|
76 | | -## Customization |
| 93 | +## 🚀 Deployment |
77 | 94 |
|
78 | | -- **Theme Options** - Modify `_config.yml` under `just_the_docs:` |
79 | | -- **Styling** - Override CSS in `assets/css/` |
80 | | -- **Layouts** - Customize Jekyll layouts in `_layouts/` |
| 95 | +This documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch. |
81 | 96 |
|
82 | | -## Resources |
| 97 | +## 📚 Resources |
83 | 98 |
|
84 | 99 | - [Just the Docs Documentation](https://just-the-docs.github.io/just-the-docs/) |
85 | | -- [Jekyll Documentation](https://jekyllrb.com/) |
| 100 | +- [Jekyll Documentation](https://jekyllrb.com/docs/) |
86 | 101 | - [GitHub Pages](https://pages.github.com/) |
0 commit comments