Skip to content

Commit a663a69

Browse files
anatolyshipitzanatolyshipitz
committed
Add initial implementation of Docs Sync Action
- Created .gitignore to exclude IDE and temporary files. - Added action.yml to define the GitHub Action for synchronizing markdown documentation with Outline Wiki. - Implemented docs-sync.sh script for handling the synchronization logic, including document creation, updating, and link processing. - Created README.md with detailed usage instructions and configuration guidelines. - Added example workflows in .github/workflows/docs-sync.yml for easy integration. - Included troubleshooting and quick start guides in docs/quick-start.md and docs/troubleshooting.md. - Established examples for various usage scenarios in docs/examples.md.
0 parents  commit a663a69

8 files changed

Lines changed: 1720 additions & 0 deletions

File tree

‎.github/workflows/docs-sync.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Sync Documentation to Outline Wiki
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths:
7+
- 'docs/**'
8+
- '**.md'
9+
workflow_dispatch:
10+
11+
jobs:
12+
sync-docs:
13+
name: Synchronizes Documentation
14+
runs-on: self-hosted
15+
16+
steps:
17+
- name: Checkout repository
18+
uses: actions/checkout@v4
19+
20+
- name: 'Sync documentation to Outline Wiki'
21+
uses: speedandfunction/docs-sync-action@main
22+
with:
23+
outline_token: ${{ secrets.OUTLINE_TOKEN }}
24+
outline_parent_document_id: ${{ vars.OUTLINE_PARENT_DOCUMENT_ID }}
25+
source_dir: './docs'
26+
verbose: 'true'

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/.idea/
2+
/.cursor/
3+
/memory-bank/

‎README.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Docs Sync Action
2+
3+
A GitHub Action that automatically synchronizes markdown documentation with [Outline Wiki](https://www.getoutline.com/), enabling seamless documentation management between your repository and wiki system.
4+
5+
## 🚀 Features
6+
7+
- **Automatic Synchronization**: Sync markdown files from your repository to Outline Wiki
8+
- **Smart Document Matching**: Matches files by title to existing wiki documents
9+
- **Hierarchical Structure**: Maintains folder structure in your wiki
10+
- **Dry Run Mode**: Test synchronization without making changes
11+
- **Verbose Logging**: Detailed logging for debugging and monitoring
12+
- **Link Replacement**: Automatically updates internal links between documents
13+
- **Error Handling**: Robust error handling with graceful degradation
14+
15+
## 📋 Prerequisites
16+
17+
- GitHub repository with markdown documentation
18+
- Outline Wiki instance with API access
19+
- Outline Wiki API token
20+
- Parent document ID in your wiki
21+
22+
## 🔧 Installation
23+
24+
### 1. Add the Action to Your Workflow
25+
26+
Create or update your `.github/workflows/docs-sync.yml`:
27+
28+
```yaml
29+
name: Sync Documentation
30+
31+
on:
32+
push:
33+
branches: [ main ]
34+
paths: [ 'docs/**' ]
35+
workflow_dispatch:
36+
37+
jobs:
38+
sync-docs:
39+
runs-on: ubuntu-latest
40+
steps:
41+
- name: Checkout code
42+
uses: actions/checkout@v4
43+
44+
- name: Sync docs to Outline Wiki
45+
uses: ./
46+
with:
47+
outline_url: 'https://your-wiki.getoutline.com/'
48+
outline_token: ${{ secrets.OUTLINE_TOKEN }}
49+
outline_parent_document_id: 'your-parent-document-id'
50+
source_dir: './docs'
51+
dry_run: 'false'
52+
verbose: 'true'
53+
```
54+
55+
### 2. Configure Secrets
56+
57+
Add your Outline Wiki API token to your repository secrets:
58+
59+
1. Go to your repository Settings → Secrets and variables → Actions
60+
2. Create a new secret named `OUTLINE_TOKEN`
61+
3. Add your Outline Wiki API token as the value
62+
63+
## ⚙️ Configuration
64+
65+
### Input Parameters
66+
67+
| Parameter | Description | Required | Default |
68+
|-----------|-------------|----------|---------|
69+
| `outline_url` | Outline Wiki base URL | Yes | `https://wiki.gluzdov.com/` |
70+
| `outline_token` | Outline Wiki API token | Yes | - |
71+
| `outline_parent_document_id` | Parent document ID in wiki | Yes | - |
72+
| `source_dir` | Source directory for markdown files | No | `./docs` |
73+
| `dry_run` | Run in dry-run mode (no changes made) | No | `false` |
74+
| `verbose` | Enable verbose logging | No | `false` |
75+
76+
### Environment Variables
77+
78+
The action uses these environment variables internally:
79+
80+
- `OUTLINE_URL`: Your Outline Wiki base URL
81+
- `OUTLINE_TOKEN`: Your API token
82+
- `OUTLINE_PARENT_DOCUMENT_ID`: Parent document ID
83+
- `SOURCE_DIR`: Source directory path
84+
- `DRY_RUN`: Dry run mode flag
85+
- `VERBOSE`: Verbose logging flag
86+
87+
## 📁 File Structure
88+
89+
Your markdown files should be organized in the source directory:
90+
91+
```
92+
docs/
93+
├── getting-started.md
94+
├── api-reference.md
95+
├── deployment/
96+
│ ├── installation.md
97+
│ └── configuration.md
98+
└── troubleshooting/
99+
└── common-issues.md
100+
```
101+
102+
## 🔍 How It Works
103+
104+
### 1. File Discovery
105+
The action scans your source directory for all `.md` files.
106+
107+
### 2. Title Extraction
108+
For each markdown file, it extracts the title from the first `#` heading.
109+
110+
### 3. Document Matching
111+
It searches your Outline Wiki for existing documents with matching titles.
112+
113+
### 4. Folder Structure
114+
The action maintains your folder structure by creating parent documents for each directory.
115+
116+
### 5. Synchronization
117+
- **Existing Documents**: Updates content if document exists
118+
- **New Documents**: Creates new documents in the appropriate location
119+
- **Link Processing**: Updates internal links between documents
120+
121+
### 6. Link Replacement
122+
In the second pass, it processes and updates internal links between documents.
123+
124+
## 📝 Markdown Requirements
125+
126+
### Title Extraction
127+
Your markdown files must have a title as the first heading:
128+
129+
```markdown
130+
# Document Title
131+
132+
Your content here...
133+
```
134+
135+
### Internal Links
136+
The action supports internal links between documents:
137+
138+
```markdown
139+
[Link to another document](another-document.md)
140+
[Link with custom text](deployment/installation.md)
141+
```
142+
143+
## 🛠️ Usage Examples
144+
145+
### Basic Usage
146+
147+
```yaml
148+
- name: Sync documentation
149+
uses: ./
150+
with:
151+
outline_url: 'https://wiki.company.com/'
152+
outline_token: ${{ secrets.OUTLINE_TOKEN }}
153+
outline_parent_document_id: 'docs-folder-id'
154+
```
155+
156+
### With Custom Source Directory
157+
158+
```yaml
159+
- name: Sync documentation
160+
uses: ./
161+
with:
162+
outline_url: 'https://wiki.company.com/'
163+
outline_token: ${{ secrets.OUTLINE_TOKEN }}
164+
outline_parent_document_id: 'docs-folder-id'
165+
source_dir: './documentation'
166+
```
167+
168+
### Dry Run Mode
169+
170+
```yaml
171+
- name: Test sync (dry run)
172+
uses: ./
173+
with:
174+
outline_url: 'https://wiki.company.com/'
175+
outline_token: ${{ secrets.OUTLINE_TOKEN }}
176+
outline_parent_document_id: 'docs-folder-id'
177+
dry_run: 'true'
178+
verbose: 'true'
179+
```
180+
181+
### Alternative Usage with Direct Script Execution
182+
183+
You can also run the synchronization script directly without GitHub Actions using curl:
184+
185+
```bash
186+
# Download and execute the script directly
187+
curl -sSL https://raw.githubusercontent.com/speedandfunction/docs-sync-action/main/docs-sync.sh | bash
188+
189+
# Or with environment variables
190+
OUTLINE_URL="https://wiki.company.com/" \
191+
OUTLINE_TOKEN="your-api-token" \
192+
OUTLINE_PARENT_DOCUMENT_ID="docs-folder-id" \
193+
SOURCE_DIR="./docs" \
194+
curl -sSL https://raw.githubusercontent.com/speedandfunction/docs-sync-action/main/docs-sync.sh | bash
195+
196+
# With additional options
197+
OUTLINE_URL="https://wiki.company.com/" \
198+
OUTLINE_TOKEN="your-api-token" \
199+
OUTLINE_PARENT_DOCUMENT_ID="docs-folder-id" \
200+
SOURCE_DIR="./docs" \
201+
DRY_RUN="true" \
202+
VERBOSE="true" \
203+
curl -sSL https://raw.githubusercontent.com/speedandfunction/docs-sync-action/main/docs-sync.sh | bash
204+
```
205+
206+
**Note**: Replace `your-username` with your actual GitHub username or organization name.
207+
208+
## 🔍 Troubleshooting
209+
210+
### Common Issues
211+
212+
1. **Authentication Errors**
213+
- Verify your API token is correct
214+
- Ensure the token has appropriate permissions
215+
216+
2. **Document Not Found**
217+
- Check that the parent document ID exists
218+
- Verify the document ID format (UUID or URL ID)
219+
220+
3. **File Processing Errors**
221+
- Ensure markdown files have proper titles
222+
- Check file permissions and encoding
223+
224+
4. **API Rate Limits**
225+
- The action includes built-in rate limiting
226+
- Consider running during off-peak hours
227+
228+
### Debug Mode
229+
230+
Enable verbose logging to see detailed information:
231+
232+
```yaml
233+
verbose: 'true'
234+
```
235+
236+
This will show:
237+
- File discovery process
238+
- Title extraction results
239+
- API calls and responses
240+
- Document creation/update operations
241+
242+
## 🔒 Security
243+
244+
- **API Tokens**: Store tokens as GitHub secrets
245+
- **Permissions**: Use tokens with minimal required permissions
246+
- **Dry Run**: Test changes with dry run mode before production
247+
- **Audit**: Review logs to verify synchronization results
248+
249+
250+
---
251+
252+
**Note**: This action is designed to work with Outline Wiki. Make sure you have the necessary permissions and API access to your wiki instance.

‎action.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: 'Docs Sync Action'
2+
description: 'Synchronize markdown documentation with Outline Wiki'
3+
inputs:
4+
outline_url:
5+
description: 'Outline Wiki base URL'
6+
required: true
7+
default: 'https://wiki.gluzdov.com/'
8+
outline_token:
9+
description: 'Outline Wiki API token'
10+
required: true
11+
outline_parent_document_id:
12+
description: 'Outline Wiki parent document ID'
13+
required: true
14+
source_dir:
15+
description: 'Source directory for markdown files'
16+
required: false
17+
default: './docs'
18+
dry_run:
19+
description: 'Run in dry-run mode'
20+
required: false
21+
default: 'false'
22+
verbose:
23+
description: 'Enable verbose logging'
24+
required: false
25+
default: 'false'
26+
27+
runs:
28+
using: 'composite'
29+
steps:
30+
- name: 'Make entrypoint executable'
31+
shell: bash
32+
run: chmod +x ${{ github.action_path }}/doc-sync.sh
33+
34+
- name: 'Run docs sync'
35+
shell: bash
36+
run: ${{ github.action_path }}/doc-sync.sh
37+
env:
38+
OUTLINE_URL: ${{ inputs.outline_url }}
39+
OUTLINE_TOKEN: ${{ inputs.outline_token }}
40+
OUTLINE_PARENT_DOCUMENT_ID: ${{ inputs.outline_parent_document_id }}
41+
SOURCE_DIR: ${{ inputs.source_dir }}
42+
DRY_RUN: ${{ inputs.dry_run }}
43+
VERBOSE: ${{ inputs.verbose }}

0 commit comments

Comments
 (0)