mirror of
https://github.com/Shiva108/ai-llm-red-team-handbook.git
synced 2026-02-12 14:42:46 +00:00
208 lines
4.6 KiB
Markdown
208 lines
4.6 KiB
Markdown
# GitHub Pages Deployment Instructions
|
|
|
|
This repository is configured for both **GitBook** and **GitHub Pages** deployment.
|
|
|
|
## GitHub Pages Setup
|
|
|
|
### 1. Enable GitHub Pages
|
|
|
|
1. Go to your repository on GitHub
|
|
2. Click **Settings** → **Pages**
|
|
3. Under **Source**, select:
|
|
- Branch: `main` (or `master`)
|
|
- Folder: `/ (root)`
|
|
4. Click **Save**
|
|
|
|
### 2. Update Configuration
|
|
|
|
Edit `_config.yml` and update these fields:
|
|
|
|
```yaml
|
|
baseurl: "/ai-llm-red-team-handbook-and-field-manual" # Updated to match GitBook
|
|
url: "https://cph-sec.gitbook.io" # Updated to match GitBook
|
|
github_username: shiva108 # Your GitHub username
|
|
linkedin_username: thorkristiansen # Your LinkedIn username
|
|
```
|
|
|
|
### 3. Access Your Site
|
|
|
|
After a few minutes, your site will be available at:
|
|
|
|
```
|
|
https://shiva108.github.io/ai-llm-red-team-handbook/
|
|
```
|
|
|
|
### 4. Custom Domain (Optional)
|
|
|
|
To use a custom domain:
|
|
|
|
1. Add a `CNAME` file to the root with your domain name
|
|
2. Configure DNS settings at your domain registrar
|
|
3. Enable HTTPS in GitHub Pages settings
|
|
|
|
---
|
|
|
|
## GitBook Setup
|
|
|
|
### Method 1: GitBook Cloud (Recommended)
|
|
|
|
1. Go to [gitbook.com](https://www.gitbook.com/)
|
|
2. Sign in and click **New Space**
|
|
3. Select **Import from GitHub**
|
|
4. Choose your repository: `shiva108/ai-llm-red-team-handbook`
|
|
5. GitBook will auto-detect `.gitbook.yaml` and `docs/SUMMARY.md` and build your book
|
|
|
|
### Method 2: GitBook CLI (Local - Legacy)
|
|
|
|
```bash
|
|
# Install GitBook CLI
|
|
npm install -g gitbook-cli
|
|
|
|
# Navigate to your repository
|
|
cd ai-llm-red-team-handbook
|
|
|
|
# Install plugins
|
|
gitbook install
|
|
|
|
# Serve locally
|
|
gitbook serve
|
|
|
|
# Build static site
|
|
gitbook build
|
|
|
|
# The built site will be in _book/ directory
|
|
```
|
|
|
|
### 3. GitBook Plugins & Branding
|
|
|
|
The repository uses a dual-configuration strategy to support both legacy builds and modern GitBook Cloud SaaS.
|
|
|
|
#### Branding (Logo & Assets)
|
|
|
|
- **Asset Location**: `docs/assets/page_header.svg`
|
|
- **Configuration**:
|
|
- `.gitbook.yaml`: Defines `branding` block pointing to `docs/assets/page_header.svg` (for new SaaS builds).
|
|
- `book.json`: Defines `insert-logo` plugin pointing to `assets/page_header.svg` (relative to `docs` root).
|
|
- **Note**: GitBook Cloud (SaaS) often ignores file-based theming. If the logo does not appear, you must set it manually via **Customize > Look & Feel** in the GitBook Dashboard.
|
|
|
|
#### Plugins (Legacy)
|
|
|
|
Defined in `book.json`:
|
|
|
|
- **search-plus**: Enhanced search
|
|
- **copy-code-button**: Copy code blocks
|
|
- **github**: GitHub integration
|
|
- **prism**: Syntax highlighting
|
|
- **page-treeview**: Chapter navigation
|
|
|
|
To install all plugins:
|
|
|
|
```bash
|
|
gitbook install
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration Files
|
|
|
|
| File | Purpose | Platform |
|
|
| ----------------- | -------------------------- | ------------ |
|
|
| `_config.yml` | Jekyll configuration | GitHub Pages |
|
|
| `.gitbook.yaml` | GitBook integration | GitBook |
|
|
| `book.json` | GitBook plugins & settings | GitBook |
|
|
| `docs/SUMMARY.md` | Table of contents | GitBook |
|
|
| `README.md` | Homepage | Both |
|
|
|
|
---
|
|
|
|
## Formatting & Asset Management
|
|
|
|
### Images
|
|
|
|
All images must be placed in `docs/assets/`.
|
|
Reference them in markdown as `` (from root docs) or `` (from subdirectories like `field_manuals/`).
|
|
|
|
### Building for Different Formats
|
|
|
|
#### PDF Export (GitBook)
|
|
|
|
```bash
|
|
gitbook pdf ./ ./handbook.pdf
|
|
```
|
|
|
|
#### eBook Export (GitBook)
|
|
|
|
```bash
|
|
# EPUB
|
|
gitbook epub ./ ./handbook.epub
|
|
|
|
# MOBI
|
|
gitbook mobi ./ ./handbook.mobi
|
|
```
|
|
|
|
---
|
|
|
|
## Customization
|
|
|
|
### GitHub Pages Theme
|
|
|
|
Change theme in `_config.yml`:
|
|
|
|
```yaml
|
|
theme: jekyll-theme-cayman # Current
|
|
# theme: jekyll-theme-minimal
|
|
# theme: jekyll-theme-slate
|
|
# theme: jekyll-theme-architect
|
|
```
|
|
|
|
### GitBook Styling
|
|
|
|
Create custom CSS in `styles/website.css`:
|
|
|
|
```css
|
|
/* Custom styles for GitBook */
|
|
.book-summary {
|
|
background: #f7f7f7;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### GitHub Pages not building?
|
|
|
|
- Check that `_config.yml` is valid YAML
|
|
- Ensure your branch name is correct in settings
|
|
- Wait 5-10 minutes for first build
|
|
|
|
### GitBook plugins not working?
|
|
|
|
```bash
|
|
# Clear cache and reinstall
|
|
rm -rf node_modules
|
|
rm -rf _book
|
|
gitbook install
|
|
gitbook serve
|
|
```
|
|
|
|
### Links broken?
|
|
|
|
- Use relative links: `[Chapter 1](docs/Chapter_01.md)`
|
|
- Avoid absolute paths
|
|
- Test locally before pushing
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Push these configuration files to GitHub
|
|
2. ✅ Enable GitHub Pages in repository settings
|
|
3. ✅ Connect to GitBook cloud (optional)
|
|
4. ✅ Customize URLs and branding
|
|
5. ✅ Share your published handbook!
|
|
|
|
---
|
|
|
|
**Your handbook is now ready for both GitBook and GitHub Pages!** 🎉
|