Skip to content

Commit b925106

Browse files
dataGriffdataGriff
committed
feat: Introduce Codebase Interface documentation and tooling
- Added comprehensive documentation covering interfaces, principles, and tooling to enhance codebase accessibility and maintainability. - Created specific markdown files for interfaces, principles, and tooling, detailing audience perspectives and recommended practices. - Implemented enhanced JavaScript functionalities for improved user experience on the landing page, including animations, search enhancements, and analytics tracking. - Developed a multi-repository search feature to streamline documentation access across different projects. - Enhanced styles for better visual presentation and responsiveness across devices. - Established a clear structure for onboarding new contributors and improving collaboration through standardized documentation.
1 parent 38d3310 commit b925106

File tree

24 files changed

+2417
-63
lines changed

24 files changed

+2417
-63
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# GitHub Actions workflow for deploying the Codebase Interface landing page
2+
3+
name: Deploy Landing Page
4+
5+
on:
6+
push:
7+
branches:
8+
- main
9+
schedule:
10+
# Daily sync at 6 AM UTC to pull updates from external repositories
11+
- cron: '0 6 * * *'
12+
workflow_dispatch:
13+
inputs:
14+
force_rebuild:
15+
description: 'Force rebuild of all content'
16+
required: false
17+
default: 'false'
18+
19+
# Allow only one deployment at a time
20+
concurrency:
21+
group: "deploy"
22+
cancel-in-progress: false
23+
24+
# Sets permissions for GitHub Pages deployment
25+
permissions:
26+
contents: read
27+
pages: write
28+
id-token: write
29+
30+
jobs:
31+
build:
32+
runs-on: ubuntu-latest
33+
steps:
34+
- name: Checkout repository
35+
uses: actions/checkout@v4
36+
with:
37+
fetch-depth: 0
38+
39+
- name: Setup Python
40+
uses: actions/setup-python@v4
41+
with:
42+
python-version: '3.x'
43+
cache: 'pip'
44+
45+
- name: Setup Task
46+
uses: arduino/setup-task@v1
47+
with:
48+
version: 3.x
49+
50+
- name: Install dependencies
51+
run: task setup
52+
53+
- name: Setup Node.js (for optimization tools)
54+
uses: actions/setup-node@v4
55+
with:
56+
node-version: '18'
57+
cache: 'npm'
58+
59+
- name: Install optimization tools
60+
run: |
61+
npm install -g htmlmin cleancss-cli
62+
sudo apt-get update
63+
sudo apt-get install -y python3-pip
64+
65+
- name: Validate configuration
66+
run: |
67+
task lint
68+
echo "✅ Configuration validation passed"
69+
70+
- name: Build landing page
71+
run: |
72+
task build:production
73+
echo "✅ Landing page built successfully"
74+
75+
- name: Upload Pages artifact
76+
uses: actions/upload-pages-artifact@v2
77+
with:
78+
path: ./site
79+
80+
deploy:
81+
needs: build
82+
environment:
83+
name: github-pages
84+
url: ${{ steps.deployment.outputs.page_url }}
85+
runs-on: ubuntu-latest
86+
steps:
87+
- name: Deploy to GitHub Pages
88+
id: deployment
89+
uses: actions/deploy-pages@v2
90+
91+
lighthouse:
92+
needs: deploy
93+
runs-on: ubuntu-latest
94+
if: github.event_name == 'push'
95+
steps:
96+
- name: Checkout repository
97+
uses: actions/checkout@v4
98+
99+
- name: Setup Node.js
100+
uses: actions/setup-node@v4
101+
with:
102+
node-version: '18'
103+
104+
- name: Install Lighthouse CI
105+
run: npm install -g @lhci/cli
106+
107+
- name: Run Lighthouse CI
108+
run: |
109+
lhci autorun --upload.target=temporary-public-storage
110+
env:
111+
LHCI_GITHUB_APP_TOKEN: ${{ secrets.GITHUB_TOKEN }}
112+
113+
- name: Comment PR with Lighthouse results
114+
if: github.event_name == 'pull_request'
115+
uses: actions/github-script@v6
116+
with:
117+
script: |
118+
github.rest.issues.createComment({
119+
issue_number: context.issue.number,
120+
owner: context.repo.owner,
121+
repo: context.repo.repo,
122+
body: '🔍 Lighthouse audit completed! Check the results in the workflow logs.'
123+
});
124+
125+
notify:
126+
needs: [deploy, lighthouse]
127+
runs-on: ubuntu-latest
128+
if: always()
129+
steps:
130+
- name: Notify deployment status
131+
run: |
132+
if [ "${{ needs.deploy.result }}" == "success" ]; then
133+
echo "🚀 Landing page successfully deployed to https://codebase-interface.github.io"
134+
else
135+
echo "❌ Deployment failed"
136+
exit 1
137+
fi

‎.markdown-link-check.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"ignorePatterns": [
3+
{
4+
"pattern": "^https://github\\.com/codebase-interface/docs"
5+
},
6+
{
7+
"pattern": "^https://github\\.com/codebase-interface/cli"
8+
},
9+
{
10+
"pattern": "^https://twitter\\.com/codebaseinterface"
11+
},
12+
{
13+
"pattern": "^https://linkedin\\.com/company/codebase-interface"
14+
}
15+
],
16+
"timeout": "20s",
17+
"retryOn429": true,
18+
"retryCount": 3,
19+
"fallbackRetryDelay": "30s",
20+
"aliveStatusCodes": [200, 206, 999]
21+
}

‎.markdownlint.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Markdown linting configuration for the landing page
2+
extends: default
3+
4+
rules:
5+
# Line length - allow longer lines for landing page content
6+
line-length:
7+
line_length: 120
8+
code_blocks: false
9+
tables: false
10+
headings: false
11+
12+
# Allow HTML in markdown for enhanced styling
13+
no-inline-html: false
14+
15+
# Allow duplicate headings for sections
16+
no-duplicate-heading: false
17+
18+
# First line heading - disabled for front matter
19+
first-line-heading: false
20+
21+
# Allow emphasis markers for styled content
22+
no-emphasis-as-heading: false
23+
24+
# Allow trailing punctuation in headers
25+
no-trailing-punctuation: false
26+
27+
# Blanks around lists - enforce proper spacing
28+
blanks-around-lists: true
29+
30+
# Blanks around fences
31+
blanks-around-fences: true
32+
33+
# No bare URLs
34+
no-bare-urls: true
35+
36+
# Proper link formatting
37+
no-space-in-links: true
38+
39+
# Code block style
40+
fenced-code-language: false
41+
42+
# List marker style
43+
ul-style:
44+
style: dash
45+
46+
# Ordered list markers
47+
ol-prefix:
48+
style: ordered
49+
50+
# No trailing spaces
51+
no-trailing-spaces: true
52+
53+
# Single trailing newline
54+
single-trailing-newline: true

‎=9.0.0‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
Collecting mkdocs-material
2+
Downloading mkdocs_material-9.7.0-py3-none-any.whl.metadata (19 kB)
3+
Requirement already satisfied: babel>=2.10 in /home/codespace/.local/lib/python3.12/site-packages (from mkdocs-material) (2.17.0)
4+
Collecting backrefs>=5.7.post1 (from mkdocs-material)
5+
Downloading backrefs-6.0.1-py312-none-any.whl.metadata (3.2 kB)
6+
Requirement already satisfied: colorama>=0.4 in /home/codespace/.local/lib/python3.12/site-packages (from mkdocs-material) (0.4.6)
7+
Requirement already satisfied: jinja2>=3.1 in /home/codespace/.local/lib/python3.12/site-packages (from mkdocs-material) (3.1.6)
8+
Collecting markdown>=3.2 (from mkdocs-material)
9+
Downloading markdown-3.10-py3-none-any.whl.metadata (5.1 kB)
10+
Collecting mkdocs-material-extensions>=1.3 (from mkdocs-material)
11+
Downloading mkdocs_material_extensions-1.3.1-py3-none-any.whl.metadata (6.9 kB)
12+
Collecting mkdocs>=1.6 (from mkdocs-material)
13+
Downloading mkdocs-1.6.1-py3-none-any.whl.metadata (6.0 kB)
14+
Collecting paginate>=0.5 (from mkdocs-material)
15+
Downloading paginate-0.5.7-py2.py3-none-any.whl.metadata (11 kB)
16+
Requirement already satisfied: pygments>=2.16 in /home/codespace/.local/lib/python3.12/site-packages (from mkdocs-material) (2.19.2)
17+
Collecting pymdown-extensions>=10.2 (from mkdocs-material)
18+
Downloading pymdown_extensions-10.17.1-py3-none-any.whl.metadata (3.1 kB)
19+
Requirement already satisfied: requests>=2.26 in /home/codespace/.local/lib/python3.12/site-packages (from mkdocs-material) (2.32.5)
20+
Requirement already satisfied: MarkupSafe>=2.0 in /home/codespace/.local/lib/python3.12/site-packages (from jinja2>=3.1->mkdocs-material) (3.0.3)
21+
Collecting click>=7.0 (from mkdocs>=1.6->mkdocs-material)
22+
Downloading click-8.3.0-py3-none-any.whl.metadata (2.6 kB)
23+
Collecting ghp-import>=1.0 (from mkdocs>=1.6->mkdocs-material)
24+
Downloading ghp_import-2.1.0-py3-none-any.whl.metadata (7.2 kB)
25+
Collecting mergedeep>=1.3.4 (from mkdocs>=1.6->mkdocs-material)
26+
Downloading mergedeep-1.3.4-py3-none-any.whl.metadata (4.3 kB)
27+
Collecting mkdocs-get-deps>=0.2.0 (from mkdocs>=1.6->mkdocs-material)
28+
Downloading mkdocs_get_deps-0.2.0-py3-none-any.whl.metadata (4.0 kB)
29+
Requirement already satisfied: packaging>=20.5 in /home/codespace/.local/lib/python3.12/site-packages (from mkdocs>=1.6->mkdocs-material) (25.0)
30+
Collecting pathspec>=0.11.1 (from mkdocs>=1.6->mkdocs-material)
31+
Downloading pathspec-0.12.1-py3-none-any.whl.metadata (21 kB)
32+
Collecting pyyaml-env-tag>=0.1 (from mkdocs>=1.6->mkdocs-material)
33+
Downloading pyyaml_env_tag-1.1-py3-none-any.whl.metadata (5.5 kB)
34+
Requirement already satisfied: pyyaml>=5.1 in /home/codespace/.local/lib/python3.12/site-packages (from mkdocs>=1.6->mkdocs-material) (6.0.3)
35+
Collecting watchdog>=2.0 (from mkdocs>=1.6->mkdocs-material)
36+
Downloading watchdog-6.0.0-py3-none-manylinux2014_x86_64.whl.metadata (44 kB)
37+
Requirement already satisfied: python-dateutil>=2.8.1 in /home/codespace/.local/lib/python3.12/site-packages (from ghp-import>=1.0->mkdocs>=1.6->mkdocs-material) (2.9.0.post0)
38+
Requirement already satisfied: platformdirs>=2.2.0 in /home/codespace/.local/lib/python3.12/site-packages (from mkdocs-get-deps>=0.2.0->mkdocs>=1.6->mkdocs-material) (4.5.0)
39+
Requirement already satisfied: six>=1.5 in /home/codespace/.local/lib/python3.12/site-packages (from python-dateutil>=2.8.1->ghp-import>=1.0->mkdocs>=1.6->mkdocs-material) (1.17.0)
40+
Requirement already satisfied: charset_normalizer<4,>=2 in /home/codespace/.local/lib/python3.12/site-packages (from requests>=2.26->mkdocs-material) (3.4.4)
41+
Requirement already satisfied: idna<4,>=2.5 in /home/codespace/.local/lib/python3.12/site-packages (from requests>=2.26->mkdocs-material) (3.11)
42+
Requirement already satisfied: urllib3<3,>=1.21.1 in /home/codespace/.local/lib/python3.12/site-packages (from requests>=2.26->mkdocs-material) (2.5.0)
43+
Requirement already satisfied: certifi>=2017.4.17 in /home/codespace/.local/lib/python3.12/site-packages (from requests>=2.26->mkdocs-material) (2025.10.5)
44+
Downloading mkdocs_material-9.7.0-py3-none-any.whl (9.3 MB)
45+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 9.3/9.3 MB 66.5 MB/s 0:00:00
46+
Downloading backrefs-6.0.1-py312-none-any.whl (398 kB)
47+
Downloading markdown-3.10-py3-none-any.whl (107 kB)
48+
Downloading mkdocs-1.6.1-py3-none-any.whl (3.9 MB)
49+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.9/3.9 MB 76.5 MB/s 0:00:00
50+
Downloading click-8.3.0-py3-none-any.whl (107 kB)
51+
Downloading ghp_import-2.1.0-py3-none-any.whl (11 kB)
52+
Downloading mergedeep-1.3.4-py3-none-any.whl (6.4 kB)
53+
Downloading mkdocs_get_deps-0.2.0-py3-none-any.whl (9.5 kB)
54+
Downloading mkdocs_material_extensions-1.3.1-py3-none-any.whl (8.7 kB)
55+
Downloading paginate-0.5.7-py2.py3-none-any.whl (13 kB)
56+
Downloading pathspec-0.12.1-py3-none-any.whl (31 kB)
57+
Downloading pymdown_extensions-10.17.1-py3-none-any.whl (266 kB)
58+
Downloading pyyaml_env_tag-1.1-py3-none-any.whl (4.7 kB)
59+
Downloading watchdog-6.0.0-py3-none-manylinux2014_x86_64.whl (79 kB)
60+
Installing collected packages: paginate, watchdog, pyyaml-env-tag, pathspec, mkdocs-material-extensions, mergedeep, markdown, click, backrefs, pymdown-extensions, mkdocs-get-deps, ghp-import, mkdocs, mkdocs-material
61+
62+
Successfully installed backrefs-6.0.1 click-8.3.0 ghp-import-2.1.0 markdown-3.10 mergedeep-1.3.4 mkdocs-1.6.1 mkdocs-get-deps-0.2.0 mkdocs-material-9.7.0 mkdocs-material-extensions-1.3.1 paginate-0.5.7 pathspec-0.12.1 pymdown-extensions-10.17.1 pyyaml-env-tag-1.1 watchdog-6.0.0

0 commit comments

Comments
 (0)