Skip to content

Add development tooling for stacks docs #554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AdekunleBamz wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add development tooling for stacks docs #554

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Stacks Docs Dockerfile
# Container for linting markdown files

FROM node:20-alpine

WORKDIR /app

RUN npm install -g markdownlint-cli@0.42.0 \
&& npm install -g cspell@8.18.0 \
&& npm install -g markdown-link-check@3.12.2 \
&& npm install -g prettier@3.3.3

COPY . ./

CMD ["markdownlint", "**/*.md", "--ignore", "node_modules"]
52 changes: 52 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Stacks Docs Development Makefile
# Helpful commands for working with the Stacks documentation repository

.PHONY: help lint lint-md spellcheck links format serve docker-build docker-run docker-stop setup env-setup info

help: ## Show this help message
@echo "Stacks Docs Commands:"
@echo ""
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-20s\033[0m %s\n", $$1, $$2}'

setup: ## Setup local tooling (optional)
@echo "No local dependencies required. Use make lint or make serve."

lint: lint-md ## Run all lint checks

lint-md: ## Lint markdown files using markdownlint-cli
@command -v npx >/dev/null 2>&1 || (echo "npx not found. Install Node.js." && exit 1)
npx --yes markdownlint-cli '**/*.md' --ignore node_modules

spellcheck: ## Spellcheck markdown files (optional)
@command -v npx >/dev/null 2>&1 || (echo "npx not found. Install Node.js." && exit 1)
npx --yes cspell '**/*.md' --no-progress

links: ## Check markdown links (optional)
@command -v npx >/dev/null 2>&1 || (echo "npx not found. Install Node.js." && exit 1)
npx --yes markdown-link-check **/*.md -q

format: ## Format markdown files (optional)
@command -v npx >/dev/null 2>&1 || (echo "npx not found. Install Node.js." && exit 1)
npx --yes prettier --write "**/*.md"

serve: ## Serve the repository over a local static server
@command -v python3 >/dev/null 2>&1 || (echo "python3 not found." && exit 1)
python3 -m http.server 8000

docker-build: ## Build Docker image for linting
docker build -t stacks-docs .

docker-run: ## Run markdown lint in Docker
docker run --rm -v $$PWD:/app -w /app stacks-docs

docker-stop: ## No-op for local dev (placeholder)
@echo "Nothing to stop."

env-setup: ## Create .env template
@echo "Creating .env file..."
@echo "# Stacks docs env" > .env
@echo "DOCS_BASE_URL=http://localhost:8000" >> .env

info: ## Show project information
@echo "Stacks Docs Repository"
@echo "Content: Markdown documentation"
20 changes: 20 additions & 0 deletions docker-compose.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
version: "3.8"

services:
lint:
build:
context: .
dockerfile: Dockerfile
volumes:
- .:/app
working_dir: /app
command: ["markdownlint", "**/*.md", "--ignore", "node_modules"]

serve:
image: python:3.12-alpine
working_dir: /app
volumes:
- .:/app
ports:
- "8000:8000"
command: ["python", "-m", "http.server", "8000"]
12 changes: 12 additions & 0 deletions init-db.sql
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
-- Stacks Docs Database Initialization
-- Placeholder for any database-backed tooling.

-- Example (PostgreSQL):
-- CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-- CREATE TABLE IF NOT EXISTS doc_events (
-- id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
-- file_path TEXT NOT NULL,
-- action TEXT NOT NULL,
-- payload JSONB,
-- created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
-- );
59 changes: 59 additions & 0 deletions setup.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
#!/usr/bin/env bash

# Stacks Docs Setup Script
# This script prepares a local environment for working with the docs repo

set -euo pipefail

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

print_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}

print_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}

print_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}

command_exists() {
command -v "$1" >/dev/null 2>&1
}

print_info "Setting up stacks docs tooling..."

if ! command_exists npx; then
print_warning "npx not found. Install Node.js to run lint/format tools."
else
print_success "npx found. You can run: make lint"
fi

if ! command_exists python3; then
print_warning "python3 not found. Install Python to serve docs locally."
else
print_success "python3 found. You can run: make serve"
fi

if [[ ! -f ".env" ]]; then
cat > .env << EOF
# Stacks docs env
DOCS_BASE_URL=http://localhost:8000
EOF
print_success ".env created."
else
print_info ".env already exists."
fi

print_success "Setup complete."
echo ""
print_info "Next steps:"
echo " 1. Lint markdown: make lint"
echo " 2. Serve docs: make serve"
echo " 3. Use Docker: docker-compose up --build"