Skip to content

Commit f452e10

Browse files
rolfedhrolfedh
committed
docs: Add aditi-docs Jekyll site template
Create a complete Jekyll documentation site template for separate GitHub Pages deployment: - Use Just the Docs theme matching main project - Include custom styles with image drop shadows - Add documentation structure: guides, tutorials, API reference, concepts - Include GitHub Actions workflow for automatic deployment - Add example content for each section - Provide setup script and detailed instructions The template is ready to be copied to /home/rolfedh/aditi-docs and deployed as a standalone documentation site at https://rolfedh.github.io/aditi-docs/
1 parent 9c19419 commit f452e10

File tree

16 files changed

+1258
-0
lines changed

16 files changed

+1258
-0
lines changed

‎ADITI_DOCS_SETUP.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Aditi Documentation Site Setup
2+
3+
I've created a complete Jekyll documentation site template for Aditi in the `aditi-docs-template` directory. This uses the same "Just the Docs" theme as the main Aditi project.
4+
5+
## What's Included
6+
7+
### Structure
8+
```
9+
aditi-docs-template/
10+
├── .github/workflows/pages.yml # GitHub Pages deployment
11+
├── _config.yml # Jekyll configuration
12+
├── _sass/custom/custom.scss # Custom styles (image shadows, etc.)
13+
├── .gitignore # Git ignore file
14+
├── Gemfile # Ruby dependencies
15+
├── README.md # Documentation README
16+
├── setup.sh # Setup script
17+
├── index.md # Home page
18+
├── guide/ # User guide section
19+
│ ├── index.md
20+
│ └── installation.md
21+
├── tutorials/ # Tutorials section
22+
│ ├── index.md
23+
│ └── first-migration.md
24+
├── api/ # API reference section
25+
│ ├── index.md
26+
│ └── rule-engine.md
27+
└── concepts/ # Concepts section
28+
└── index.md
29+
```
30+
31+
### Features
32+
33+
1. **Just the Docs Theme** - Same professional theme as the main project
34+
2. **Custom Styling** - Drop shadows on images, API endpoint styling
35+
3. **Search Functionality** - Built-in search across all documentation
36+
4. **GitHub Pages Ready** - Includes workflow for automatic deployment
37+
5. **Responsive Design** - Works great on mobile and desktop
38+
6. **Navigation Structure** - Organized sections for different content types
39+
40+
## Setup Instructions
41+
42+
### Step 1: Copy to Target Location
43+
44+
```bash
45+
cp -r aditi-docs-template /home/rolfedh/aditi-docs
46+
cd /home/rolfedh/aditi-docs
47+
```
48+
49+
### Step 2: Initialize Git and Run Setup
50+
51+
```bash
52+
chmod +x setup.sh
53+
./setup.sh
54+
```
55+
56+
### Step 3: Create GitHub Repository
57+
58+
1. Go to https://github.com/new
59+
2. Create a new repository named `aditi-docs`
60+
3. Don't initialize with README (we already have one)
61+
62+
### Step 4: Connect and Push
63+
64+
```bash
65+
git remote add origin https://github.com/rolfedh/aditi-docs.git
66+
git push -u origin main
67+
```
68+
69+
### Step 5: Enable GitHub Pages
70+
71+
1. Go to Settings > Pages in your repository
72+
2. Source: Deploy from a branch
73+
3. Branch: main
74+
4. Folder: / (root)
75+
5. Click Save
76+
77+
### Step 6: Wait for Deployment
78+
79+
GitHub will automatically build and deploy your site. It will be available at:
80+
https://rolfedh.github.io/aditi-docs/
81+
82+
## Local Development
83+
84+
To run the site locally:
85+
86+
```bash
87+
cd /home/rolfedh/aditi-docs
88+
bundle install
89+
bundle exec jekyll serve
90+
```
91+
92+
Visit: http://localhost:4000/aditi-docs/
93+
94+
## Customization
95+
96+
### Adding New Pages
97+
98+
1. Create a new `.md` file in the appropriate directory
99+
2. Add front matter:
100+
```yaml
101+
---
102+
layout: default
103+
title: Page Title
104+
parent: Parent Section
105+
nav_order: 1
106+
---
107+
```
108+
109+
### Modifying Styles
110+
111+
Edit `_sass/custom/custom.scss` to add custom styles.
112+
113+
### Changing Theme Settings
114+
115+
Edit `_config.yml` to modify:
116+
- Site title and description
117+
- Navigation behavior
118+
- Search settings
119+
- Footer content
120+
121+
## Next Steps
122+
123+
1. **Add More Content** - Fill out the remaining sections
124+
2. **Add Screenshots** - Place images in `/assets/images/`
125+
3. **Create More Tutorials** - Add step-by-step guides
126+
4. **API Documentation** - Document all public APIs
127+
5. **Link from Main Repo** - Add link to docs from main Aditi README
128+
129+
## Notes
130+
131+
- The baseurl is set to `/aditi-docs` to match the GitHub Pages URL
132+
- All internal links should use `{{ site.baseurl }}` prefix
133+
- The GitHub workflow automatically builds and deploys on push to main
134+
- Custom styles include drop shadows for images and special API endpoint formatting

‎aditi-docs-template/.github/workflows/pages.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Sample workflow for building and deploying a Jekyll site to GitHub Pages
2+
name: Deploy Jekyll site to Pages
3+
4+
on:
5+
# Runs on pushes targeting the default branch
6+
push:
7+
branches: ["main"]
8+
9+
# Allows you to run this workflow manually from the Actions tab
10+
workflow_dispatch:
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
19+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
20+
concurrency:
21+
group: "pages"
22+
cancel-in-progress: false
23+
24+
jobs:
25+
# Build job
26+
build:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
- name: Setup Ruby
32+
uses: ruby/setup-ruby@v1
33+
with:
34+
ruby-version: '3.1'
35+
bundler-cache: true # runs 'bundle install' and caches installed gems
36+
- name: Setup Pages
37+
id: pages
38+
uses: actions/configure-pages@v4
39+
- name: Build with Jekyll
40+
# Outputs to the './_site' directory by default
41+
run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
42+
env:
43+
JEKYLL_ENV: production
44+
- name: Upload artifact
45+
# Automatically uploads an artifact from the './_site' directory by default
46+
uses: actions/upload-pages-artifact@v3
47+
48+
# Deployment job
49+
deploy:
50+
environment:
51+
name: github-pages
52+
url: ${{ steps.deployment.outputs.page_url }}
53+
runs-on: ubuntu-latest
54+
needs: build
55+
steps:
56+
- name: Deploy to GitHub Pages
57+
id: deployment
58+
uses: actions/deploy-pages@v4

‎aditi-docs-template/.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
_site
2+
.sass-cache
3+
.jekyll-cache
4+
.jekyll-metadata
5+
vendor
6+
.bundle
7+
Gemfile.lock
8+
.DS_Store
9+
*.swp
10+
*~

‎aditi-docs-template/Gemfile‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
source 'https://rubygems.org'
2+
3+
gem "jekyll", "~> 4.3.0"
4+
5+
group :jekyll_plugins do
6+
gem "jekyll-remote-theme"
7+
gem "jekyll-seo-tag"
8+
gem "jekyll-include-cache"
9+
end
10+
11+
# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
12+
# and associated library.
13+
platforms :mingw, :x64_mingw, :mswin, :jruby do
14+
gem "tzinfo", ">= 1", "< 3"
15+
gem "tzinfo-data"
16+
end
17+
18+
# Performance-booster for watching directories on Windows
19+
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
20+
21+
# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
22+
# do not have a Java counterpart.
23+
gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

‎aditi-docs-template/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Aditi Documentation
2+
3+
This repository contains the documentation for [Aditi](https://github.com/rolfedh/aditi), an AsciiDoc to DITA integration tool.
4+
5+
## Setup
6+
7+
1. Clone this repository to `/home/rolfedh/aditi-docs`
8+
2. Install Jekyll dependencies:
9+
```bash
10+
bundle install
11+
```
12+
3. Run locally:
13+
```bash
14+
bundle exec jekyll serve
15+
```
16+
4. Visit http://localhost:4000/aditi-docs/
17+
18+
## Deployment
19+
20+
This site is configured for GitHub Pages. Simply push to the `main` branch and GitHub will automatically build and deploy the site.
21+
22+
## Structure
23+
24+
- `/guide/` - User guide and installation instructions
25+
- `/tutorials/` - Step-by-step tutorials
26+
- `/api/` - API reference documentation
27+
- `/concepts/` - Conceptual documentation
28+
- `/assets/` - Images and other assets
29+
30+
## Theme
31+
32+
This documentation uses the [Just the Docs](https://just-the-docs.github.io/just-the-docs/) Jekyll theme.
33+
34+
## Contributing
35+
36+
Please see the main [Aditi repository](https://github.com/rolfedh/aditi) for contribution guidelines.

‎aditi-docs-template/_config.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
title: Aditi Documentation
2+
description: Comprehensive documentation for Aditi - AsciiDoc to DITA integration tool
3+
baseurl: "/aditi-docs"
4+
url: "https://rolfedh.github.io"
5+
6+
# Modern theme - Just the Docs
7+
remote_theme: just-the-docs/just-the-docs@v0.8.2
8+
plugins:
9+
- jekyll-remote-theme
10+
11+
# Just the Docs theme configuration
12+
color_scheme: light
13+
search_enabled: true
14+
15+
# Custom styles
16+
sass:
17+
sass_dir: _sass
18+
search:
19+
# Split pages into sections that can be searched individually
20+
heading_level: 2
21+
# Maximum amount of previews per search result
22+
previews: 2
23+
# Maximum amount of words to display before a matched word in the preview
24+
preview_words_before: 3
25+
# Maximum amount of words to display after a matched word in the preview
26+
preview_words_after: 3
27+
# Set the search token separator
28+
tokenizer_separator: /[\s\-/]+/
29+
# Display the relative url in search results
30+
rel_url: true
31+
# Enable or disable the search button that appears in the bottom right corner of every page
32+
button: false
33+
34+
# Footer configuration
35+
footer_content: "Copyright &copy; 2025 Aditi. Distributed under the MIT License."
36+
37+
# Social links (optional)
38+
gh_edit_link: true
39+
gh_edit_repository: "https://github.com/rolfedh/aditi-docs"
40+
gh_edit_branch: "main"
41+
gh_edit_source: .
42+
gh_edit_view_mode: "tree"
43+
44+
# Navigation structure
45+
nav_sort: case_insensitive
46+
47+
# Markdown configuration
48+
markdown: kramdown
49+
kramdown:
50+
input: GFM
51+
syntax_highlighter: rouge
52+
53+
# Collections
54+
collections:
55+
tutorials:
56+
output: true
57+
permalink: /tutorials/:name/
58+
api:
59+
output: true
60+
permalink: /api/:name/
61+
62+
# Exclude from processing
63+
exclude:
64+
- README.md
65+
- Gemfile
66+
- Gemfile.lock
67+
- node_modules
68+
- vendor
69+
- "*.sh"
70+
- drafts/

0 commit comments

Comments
 (0)