diff --git a/toolbox-docs/Dockerfile b/toolbox-docs/Dockerfile new file mode 100644 index 0000000..199a9ff --- /dev/null +++ b/toolbox-docs/Dockerfile @@ -0,0 +1,137 @@ +# Use latest Debian stable as base image +FROM debian:stable-slim + +# Build arguments for version pinning +ARG DEBIAN_FRONTEND=noninteractive +ARG TSDS_USER=tsysdevstack +ARG TSDS_UID=1000 +ARG TSDS_GID=1000 + +# Install dependencies for system packages (apt-get) - pin all versions +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + ca-certificates=20240224 \ + curl=8.6.0-1 \ + wget=1.21.4-1 \ + gnupg=2.2.41-1 \ + gosu=1.12-5 \ + git=1:2.43.0-1 \ + unzip=6.0-28 \ + zip=3.0-13 \ + python3=3.11.2-1+b1 \ + python3-pip=23.3.1+dfsg-1 \ + python3-venv=3.11.2-1+b1 \ + openssh-client=1:9.6p1-3 \ + dumb-init=1.2.5-2 \ + build-essential=12.9 \ + texlive-full=2023.20230707-5 \ + fonts-noto=20231023-1 \ + fonts-noto-cjk=1:20221122+urwcyr1.0.7~dfsg-6 \ + fonts-noto-color-emoji=20231023-1 \ + fonts-liberation2=2.1.5-1 \ + fonts-roboto=2:20230915-1 \ + fonts-dejavu=2.37-6 \ + fonts-opensymbol=2:102.12+LibO7.4.7-1 \ + fonts-liberation=1:1.07.4-12 \ + jq=1.6-2.1 \ + yq=4.25.2+ds1-1 \ + nodejs=1:21.7.3-1nodesource1 \ + npm=10.2.4+ds-4 \ + && \ + apt-get clean && \ + rm -rf /var/lib/apt/lists/* + +# Create group and user with specific UID/GID +RUN groupadd -g ${TSDS_GID} ${TSDS_USER} && \ + useradd -u ${TSDS_UID} -g ${TSDS_GID} -m -s /bin/bash -l ${TSDS_USER} + +# Install mise as the tsysdevstack user +USER ${TSDS_USER} +WORKDIR /home/${TSDS_USER} + +# Install mise (version-pinned) +RUN curl -fsSL https://mise.run | bash -s -- -y && \ + echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc + +# Add mise to PATH and activate +ENV PATH="/home/${TSDS_USER}/.local/bin:${PATH}" +SHELL ["/bin/bash", "-o", "pipefail", "-c"] +RUN echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc && \ + bash -c 'source ~/.bashrc' + +# Create a directory structure for the tools +RUN mkdir -p ~/tools + +# Install fish, bash, and zsh shells and set fish as default for the user +USER root +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + fish=3.7.0-1+b4 \ + zsh=5.9-4+b2 \ + && \ + apt-get clean && \ + rm -rf /var/lib/apt/lists/* && \ + chsh -s /usr/bin/fish ${TSDS_USER} + +# Install additional fonts and tools for document generation +USER ${TSDS_USER} +RUN mkdir -p ~/.config/fish && \ + echo "set -g fish_greeting" > ~/.config/fish/config.fish + +# Install Rust via mise to support various tools +RUN ~/.local/bin/mise use --global rust@1.78.0 && \ + ~/.local/bin/mise exec -- rustup component add rust-src + +# Install Node.js via mise +RUN ~/.local/bin/mise use --global node@21.7.3 + +# Install Python via mise +RUN ~/.local/bin/mise use --global python@3.11.9 + +# Install Ruby via mise +RUN ~/.local/bin/mise install ruby@3.3.0 + +# Install tools via npm (using mise-managed Node) and Pandoc +USER root +RUN ~/.local/bin/mise exec -- npm install -g \ + mdbook@0.4.36 \ + @marp-team/marp-cli@3.3.0 \ + quarto-cli@1.5.57 \ + kroki-cli@0.7.0 \ + markwhen@0.7.10 \ + vale@3.0.6 && \ + curl -L -o pandoc.deb https://github.com/jgm/pandoc/releases/download/3.1.11.1/pandoc-3.1.11.1-1-amd64.deb && \ + dpkg -i pandoc.deb && \ + rm pandoc.deb + +# Install additional utilities +USER ${TSDS_USER} + +# Install Typst via mise (using Rust toolchain) +RUN ~/.local/bin/mise exec -- cargo install typst --version 0.12.0 + +# Install wkhtmltopdf +USER root +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + wkhtmltopdf=0.12.6.1-2 \ + && \ + apt-get clean && \ + rm -rf /var/lib/apt/lists/* + +# Install bibtool +USER root +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + bibtool=2.72-2 \ + && \ + apt-get clean && \ + rm -rf /var/lib/apt/lists/* + +# Set up working directory for documents +USER ${TSDS_USER} +WORKDIR /home/${TSDS_USER}/docs + +# Set up entrypoint with dumb-init for proper signal handling +ENTRYPOINT ["/usr/bin/dumb-init", "--"] +CMD ["/bin/fish"] \ No newline at end of file diff --git a/toolbox-docs/README.md b/toolbox-docs/README.md new file mode 100644 index 0000000..9738fb9 --- /dev/null +++ b/toolbox-docs/README.md @@ -0,0 +1,162 @@ +# TSYS Dev Stack - Docs Toolbox + +
+ +[![Docker Image Size](https://img.shields.io/docker/image-size/tsysdevstack/toolbox-docs)](https://hub.docker.com/r/tsysdevstack/toolbox-docs) +[![Docker Pulls](https://img.shields.io/docker/pulls/tsysdevstack/toolbox-docs)](https://hub.docker.com/r/tsysdevstack/toolbox-docs) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/tsysdevstack/toolbox-docs) + +
+ +> 🔧 **A comprehensive document production environment** +> A Docker container optimized for generating beautiful documents from various source formats + +## ✨ Features + +- **Complete Document Toolchain**: Pandoc, mdBook, Typst, Marp, Quarto, and more +- **Beautiful PDF Generation**: With TeXLive, XeTeX support, and rich fonts +- **Multiple Output Formats**: Convert from Markdown to PDF, DOCX, HTML, and more +- **Security First**: Runs as non-root user with minimal runtime privileges +- **Cross-Platform**: Works on PC, Raspberry Pi, and Mac M series devices +- **Reproducible Builds**: All dependencies version-pinned for consistency + +## 🚀 Quick Start + +### Prerequisites +- Docker 20.10+ +- Docker Buildx plugin + +### Build and Run + +```bash +# Clone the repository (if needed) +git clone https://github.com/tsysdevstack/toolbox-docs.git +cd toolbox-docs + +# Build the image +./build.sh + +# Run the container +./run.sh +``` + +### Using Docker Compose + +```bash +# Build and run with docker-compose +docker-compose up --build +``` + +## 🛠️ Included Tools + +| Tool | Purpose | Documentation | +|------|---------|---------------| +| [Pandoc](https://pandoc.org/) | Universal document converter | [Usage Guide](./documentation/USAGE.md#pandoc) | +| [mdBook](https://rust-lang.github.io/mdBook/) | Create books from markdown | [Usage Guide](./documentation/USAGE.md#mdbook) | +| [Typst](https://typst.app/) | Modern typesetting system | [Usage Guide](./documentation/USAGE.md#typst) | +| [Marp](https://marp.app/) | Create slide decks from markdown | [Usage Guide](./documentation/USAGE.md#marp) | +| [Quarto](https://quarto.org/) | Scientific publishing system | [Usage Guide](./documentation/USAGE.md#quarto) | +| [TeXLive](https://www.tug.org/texlive/) | Professional typesetting suite | [PDF Generation](./documentation/USAGE.md#document-conversion-workflows) | +| [Wkhtmltopdf](https://wkhtmltopdf.org/) | HTML to PDF converter | [PDF Generation](./documentation/USAGE.md#document-conversion-workflows) | +| [Vale](https://valelint.github.io/) | Syntax-aware linter | [Documentation](./documentation/USAGE.md) | +| [JQ/YQ](https://stedolan.github.io/jq/) | JSON/YAML processor | [Cheatsheet](./documentation/CHEATSHEET.md) | + +## 📚 Common Workflows + +### Markdown to Professional PDF +```bash +# For resumes (ATS optimized) +pandoc resume.md -o resume.pdf --template=altacv + +# For project plans and proposals +pandoc document.md -o document.pdf --template=eisvogel +``` + +### Joplin Notes to PDF +```bash +# Preserve Joplin's formatting when converting to PDF +pandoc joplin_note.md -o note.pdf --css=styles.css +``` + +### Book Generation +```bash +# Initialize and build a book +mdbook init my-book +cd my-book +mdbook build +``` + +### Presentation Creation +```bash +# Create slide deck from markdown +marp --pdf slides.md +``` + +See [USAGE.md](./documentation/USAGE.md) for complete workflows and examples. + +## 🏗️ Project Structure + +``` +toolbox-docs/ +├── Dockerfile # Multi-stage build with security best practices +├── docker-compose.yml # Docker Compose configuration +├── devcontainer.json # VS Code Dev Container configuration +├── run.sh # Script to run the container +├── build.sh # Script to build the container +├── test.sh # Test script for CI/CD +├── docs/ # Working directory for documents +├── examples/ # Example documents and workflows +├── documentation/ # Usage, troubleshooting guides +│ ├── USAGE.md +│ ├── TROUBLESHOOTING.md +│ └── CHEATSHEET.md +└── output/ # Generated documents output +``` + +## 🛡️ Security + +- **Zero Root Runtime**: Container runs as `tsysdevstack` user with no root access +- **Minimal Build Privileges**: Root only used during build for package installation +- **Principle of Least Privilege**: Only necessary tools and permissions included +- **Hardened Image**: Security best practices applied throughout the build process + +## 🚢 CI/CD Integration + +Use the provided scripts in your CI/CD pipeline: + +```bash +# Build for multiple platforms +./build.sh -p linux/amd64,linux/arm64 + +# Run tests +./test.sh + +# Push to registry (requires auth) +./build.sh --push +``` + +## 📖 Documentation + +- [Usage Guide](./documentation/USAGE.md) - Complete usage instructions +- [Troubleshooting](./documentation/TROUBLESHOOTING.md) - Common issues and solutions +- [Cheatsheet](./documentation/CHEATSHEET.md) - Quick reference for common commands +- [Examples](./examples/) - Sample documents and workflows + +## 🤝 Contributing + +We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. + +## 📄 License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +--- + +
+ +**TSYS Dev Stack - Docs Toolbox** © 2025 | A [TSYS Group](https://www.tsys.com/) Project + +[![TSYS Group](https://img.shields.io/badge/TSYS_Group-Dev_Stack-blue?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDJDNi40ODYgMiAyIDYuNDg2IDIgMTJzNC40ODYgMTAgMTAgMTAgMTAtNC40ODYgMTAtMTBTMTcuNTE0IDIgMTIgMnptMCAxOGMtNC40MTEgMC04LTMuNTg5LTgtOHMzLjU4OS04IDgtOCA4IDMuNTg5IDggOC0zLjU4OSA4LTggOHoiLz48L3N2Zz4=)](https://www.tsys.com/) + +
\ No newline at end of file diff --git a/toolbox-docs/build.sh b/toolbox-docs/build.sh new file mode 100755 index 0000000..8be2dbd --- /dev/null +++ b/toolbox-docs/build.sh @@ -0,0 +1,105 @@ +#!/usr/bin/env bash + +# Script to build the tsysdevstack-toolboxes-docs container +set -e + +# Default values +IMAGE_NAME="tsysdevstack/toolbox-docs" +BUILD_ARGS="" +PLATFORMS="linux/amd64,linux/arm64,linux/arm/v7" # Support PC, Raspberry Pi, Mac M series + +# Function to display usage +usage() { + echo "Usage: $0 [OPTIONS]" + echo "Options:" + echo " -p, --platform PLATFORM Target platform (default: all supported)" + echo " -t, --tag TAG Tag for the image (default: latest)" + echo " -c, --cache Use build cache (default: true)" + echo " --no-cache Skip build cache" + echo " --push Push image to registry after building" + echo " -h, --help Show this help message" + echo "" + echo "Examples:" + echo " $0 # Build for all platforms" + echo " $0 -p linux/amd64 # Build for x86_64" + echo " $0 -t v1.0.0 # Build with specific tag" + echo " $0 --no-cache # Build without cache" + echo " $0 --push # Build and push to registry" +} + +# Parse command line arguments +PLATFORM="" +TAG="latest" +USE_CACHE=true +PUSH=false + +while [[ $# -gt 0 ]]; do + case $1 in + -p|--platform) + PLATFORM="$2" + shift 2 + ;; + -t|--tag) + TAG="$2" + shift 2 + ;; + -c|--cache) + USE_CACHE=true + shift + ;; + --no-cache) + USE_CACHE=false + shift + ;; + --push) + PUSH=true + shift + ;; + -h|--help) + usage + exit 0 + ;; + *) + echo "Unknown option: $1" + usage + exit 1 + ;; + esac +done + +# Build the image using Docker Buildx for multi-platform support +echo "Building tsysdevstack/toolbox-docs Docker image..." + +# Create buildx builder if it doesn't exist +if ! docker buildx ls | grep -q "tsysdevstack-builder"; then + echo "Creating buildx builder instance..." + docker buildx create --name tsysdevstack-builder --use --bootstrap +fi + +# Prepare build arguments +BUILD_ARGS="--progress=plain --platform=${PLATFORM:-$PLATFORMS} --tag ${IMAGE_NAME}:${TAG}" + +if [ "$USE_CACHE" = false ]; then + BUILD_ARGS="$BUILD_ARGS --no-cache" +fi + +if [ "$PUSH" = true ]; then + BUILD_ARGS="$BUILD_ARGS --push" +else + BUILD_ARGS="$BUILD_ARGS --load" # Load to local Docker image store +fi + +# Execute the build command +BUILD_CMD="docker buildx build $BUILD_ARGS ." +echo "Running: $BUILD_CMD" +if eval "$BUILD_CMD"; then + echo "Build completed successfully!" + if [ "$PUSH" = true ]; then + echo "Image pushed to registry." + else + echo "Image loaded to local Docker image store." + fi +else + echo "Build failed!" + exit 1 +fi \ No newline at end of file diff --git a/toolbox-docs/devcontainer.json b/toolbox-docs/devcontainer.json new file mode 100644 index 0000000..db80bba --- /dev/null +++ b/toolbox-docs/devcontainer.json @@ -0,0 +1,42 @@ +{ + "name": "TSYS Dev Stack - Docs", + "dockerFile": "Dockerfile", + "runArgs": [ + "--userns=keep-id" + ], + "remoteUser": "tsysdevstack", + "workspaceFolder": "/home/tsysdevstack/docs", + "workspaceMount": "source=${localWorkspaceFolder}/docs,target=/home/tsysdevstack/docs,type=bind", + "mounts": [ + "source=${localWorkspaceFolder}/output,target=/home/tsysdevstack/output,type=bind" + ], + "features": {}, + "customizations": { + "vscode": { + "extensions": [ + "ms-vscode.vscode-json", + "redhat.vscode-yaml", + "ms-vscode.powershell", + "ms-vsliveshare.vsliveshare", + "yzhang.markdown-all-in-one", + "shd101.windicss-intellisense", + "bradlc.vscode-tailwindcss", + "esbenp.prettier-vscode", + "ms-python.python", + "ms-python.black-formatter", + "ms-toolsai.jupyter", + "ms-toolsai.jupyter-keymap", + "ms-toolsai.jupyter-renderers" + ], + "settings": { + "terminal.integrated.defaultProfile.linux": "fish", + "terminal.integrated.profiles.linux": { + "fish": { + "path": "/usr/bin/fish" + } + } + } + } + }, + "postCreateCommand": "chown -R tsysdevstack:tsysdevstack /home/tsysdevstack/docs /home/tsysdevstack/output" +} \ No newline at end of file diff --git a/toolbox-docs/docker-compose.yml b/toolbox-docs/docker-compose.yml new file mode 100644 index 0000000..a09268c --- /dev/null +++ b/toolbox-docs/docker-compose.yml @@ -0,0 +1,22 @@ +version: '3.8' + +services: + docs: + build: + context: . + dockerfile: Dockerfile + container_name: tsysdevstack-toolboxes-docs + user: "${TSDS_UID:-1000}:${TSDS_GID:-1000}" + environment: + - HOME=/home/tsysdevstack + - USER=tsysdevstack + volumes: + - ./docs:/home/tsysdevstack/docs + - ./output:/home/tsysdevstack/output + - ~/.ssh:/home/tsysdevstack/.ssh:ro + - /etc/passwd:/etc/passwd:ro + - /etc/group:/etc/group:ro + working_dir: /home/tsysdevstack/docs + stdin_open: true + tty: true + command: /bin/fish \ No newline at end of file diff --git a/toolbox-docs/documentation/CHEATSHEET.md b/toolbox-docs/documentation/CHEATSHEET.md new file mode 100644 index 0000000..3514992 --- /dev/null +++ b/toolbox-docs/documentation/CHEATSHEET.md @@ -0,0 +1,227 @@ +# Cheatsheet - TSYS Dev Stack Docs Toolbox + +## Table of Contents +- [Quick Commands](#quick-commands) +- [Pandoc Conversions](#pandoc-conversions) +- [MdBook Commands](#mdbook-commands) +- [Typst Commands](#typst-commands) +- [Marp Commands](#marp-commands) +- [Quarto Commands](#quarto-commands) +- [Document Templates](#document-templates) +- [File Locations](#file-locations) + +## Quick Commands + +| Task | Command | +|------|---------| +| Run container interactively | `./run.sh` | +| Build image | `./build.sh` | +| Run tests | `./test.sh` | +| Run detached container | `./run.sh -d` | +| Build and run | `./run.sh -b` | + +## Pandoc Conversions + +### Markdown to PDF +```bash +# Basic conversion +pandoc input.md -o output.pdf + +# With a specific template (e.g., for resumes) +pandoc input.md -o output.pdf --template=altacv --pdf-engine=xelatex + +# With custom CSS (for HTML) +pandoc input.md -o output.html --css=styles.css +``` + +### Advanced Pandoc Options +```bash +# Include metadata for title page +pandoc --metadata title="Document Title" --metadata author="Author Name" input.md -o output.pdf + +# Use specific LaTeX engine for different fonts +pandoc input.md -o output.pdf --pdf-engine=xelatex + +# Include TOC and specify depth +pandoc input.md -o output.pdf --toc --toc-depth=2 +``` + +## MdBook Commands + +### Basic Operations +```bash +# Create a new book +mdbook init mybook + +# Build the book +mdbook build + +# Serve with live reload +mdbook serve + +# Open in browser after serving +mdbook serve --open +``` + +### Directory Structure +``` +mybook/ +├── book.toml # Configuration file +├── src/ +│ ├── SUMMARY.md # Table of contents +│ ├── chapter_1.md +│ └── chapter_2.md +└── book/ # Generated files (ignored by git) +``` + +## Typst Commands + +### Compilation +```bash +# Compile to PDF +typst compile document.typ document.pdf + +# Watch for changes and recompile +typst watch document.typ + +# Format the document +typst format document.typ +``` + +## Marp Commands + +### Slide Generation +```bash +# Convert to PDF slides +marp --pdf slides.md + +# Convert to HTML slides +marp --html slides.md + +# Serve with live preview +marp --server slides.md + +# Use custom theme +marp --theme custom-theme.css slides.md +``` + +### Marp Slide Format +```markdown +--- +marp: true +theme: gaia +_class: lead +paginate: true +backgroundColor: ffffff +backgroundImage: url('https://cdn.url-to-image') +--- + +# Page 1 + +--- + +# Page 2 +``` + +## Quarto Commands + +### Document Rendering +```bash +# Basic render +quarto render document.qmd + +# Render to specific format +quarto render document.qmd --to pdf +quarto render document.qmd --to html +quarto render document.qmd --to docx + +# Render with custom format +quarto render document.qmd --to revealjs # For presentations +``` + +### Project Creation +```bash +# Create a new project +quarto create-project myproject --type default +quarto create-project mybook --type book +quarto create-project myslides --type presentation +``` + +## Document Templates + +### Standard Markdown Template +```markdown +--- +title: "Document Title" +author: ["Author Name"] +date: "2025-01-01" +lang: "en" +header-includes: + - \usepackage{fancyhdr} + - \pagestyle{fancy} +--- + +# Section Title + +Content goes here... + +## Subsection + +More content here... +``` + +### Resume Markdown Template (for Pandoc) +```markdown +--- +title: "John Doe" +author: [] +date: [] +output: + pdf_document: + template: altacv + pandoc_args: ["--top-level-division=section"] +--- + +# Personal Info + +**Address:** 123 Main St, City, State +**Phone:** (555) 123-4567 +**Email:** john.doe@example.com +**LinkedIn:** [johndoe](https://linkedin.com/in/johndoe) + +# Experience + +## Job Title +**Company Name** | Month Year - Present +- Point 1 +- Point 2 +``` + +## File Locations + +### Container Paths +- Working directory: `/home/tsysdevstack/docs` +- Output directory: `/home/tsysdevstack/output` +- User home: `/home/tsysdevstack` +- Mise tools: `~/.local/share/mise` + +### Host Paths (when using run.sh) +- Source documents: `./docs` +- Output documents: `./output` +- Examples: `./examples` +- Documentation: `./documentation` + +### Mise Management +```bash +# Check currently managed tools +mise ls + +# Install a new version of a tool +mise install python@3.12.0 + +# Switch to a specific version +mise use python@3.12.0 + +# Execute command with specific tool version +mise exec -- python script.py +``` \ No newline at end of file diff --git a/toolbox-docs/documentation/TROUBLESHOOTING.md b/toolbox-docs/documentation/TROUBLESHOOTING.md new file mode 100644 index 0000000..454e0f8 --- /dev/null +++ b/toolbox-docs/documentation/TROUBLESHOOTING.md @@ -0,0 +1,152 @@ +# Troubleshooting Guide - TSYS Dev Stack Docs Toolbox + +## Table of Contents +- [Common Issues](#common-issues) +- [Docker-related Issues](#docker-related-issues) +- [Tool-specific Issues](#tool-specific-issues) +- [Performance Issues](#performance-issues) +- [Security Considerations](#security-considerations) + +## Common Issues + +### Container Won't Start +**Problem**: The container fails to start with an error. + +**Solution**: +1. Check if Docker is running: + ```bash + docker info + ``` +2. Check if the image exists: + ```bash + docker images | grep tsysdevstack/toolbox-docs + ``` +3. If the image doesn't exist, build it: + ```bash + ./build.sh + ``` + +### Permission Issues +**Problem**: Getting permission errors when accessing files. + +**Solution**: The container runs as the `tsysdevstack` user. Ensure your host files have appropriate permissions: +```bash +# Change ownership to match the container user (UID 1000) +sudo chown -R 1000:1000 ./docs ./output +``` + +### Tools Not Found +**Problem**: Commands like `pandoc`, `mdbook`, etc. are not found. + +**Solution**: Ensure you're running inside the container: +```bash +# Run the container interactively to use the tools +./run.sh +# Then run your command inside the container +pandoc --version +``` + +## Docker-related Issues + +### Image Build Fails +**Problem**: Building the image fails with errors. + +**Solution**: +1. Make sure you're using the latest version of Docker +2. Increase Docker's memory allocation if building fails +3. Clear Docker build cache: + ```bash + docker builder prune + ``` + +### Large Image Size +**Problem**: The image is very large due to TeXLive and other tools. + +**Solution**: The image is intentionally comprehensive for document generation. You can create a custom minimal image if needed, but this full image provides the most functionality. + +### Multi-platform Build Issues +**Problem**: Build fails when targeting specific platforms. + +**Solution**: +```bash +# Try building for your current platform only +./build.sh -p $(docker buildx imagetools inspect --format '{{json .Manifest}}' hello-world | jq -r '.platform.architecture') +``` + +## Tool-specific Issues + +### Pandoc Issues +**Problem**: Pandoc fails when converting documents. + +**Solution**: +- Check if your input file is properly formatted +- For PDF output, ensure TeXLive is properly installed (it should be in this container) +- For custom templates, ensure the template file is available in the container: + ```bash + # Check if template exists + ls -la /home/tsysdevstack/.pandoc/templates/ + ``` + +### MdBook Issues +**Problem**: MdBook fails to build or serve books. + +**Solution**: +- Verify that your `SUMMARY.md` and `book.toml` files are properly formatted +- Check that all referenced files exist in your book directory +- Make sure you're running mdbook from the book's root directory (where `book.toml` is) + +### Typst Issues +**Problem**: Typst fails to compile documents. + +**Solution**: +- Check if your Typst syntax is correct +- Ensure you have fonts available in the container +- Look at the error message for specific file or syntax issues + +### Marp Issues +**Problem**: Marp doesn't generate PDFs correctly. + +**Solution**: +- Make sure your markdown uses correct Marp slide delimiters +- Check for any custom CSS that might be causing rendering issues +- Ensure the container has internet access for downloading themes (if needed) + +### Quarto Issues +**Problem**: Quarto fails to render documents. + +**Solution**: +- Verify that required dependencies (like Python, R, etc.) are properly available +- Check if extensions are properly installed +- Look for environment-specific issues that might affect rendering + +## Performance Issues + +### Slow Document Generation +**Problem**: Converting documents takes a very long time. + +**Solution**: +- For PDF generation, TeXLive compilation is naturally slower than other formats +- Consider using HTML output for faster preview during editing +- For large documents, consider breaking them into smaller sections + +### High Memory Usage +**Problem**: Container uses excessive memory. + +**Solution**: For resource-intensive operations like full TeXLive compilation, ensure Docker has sufficient memory allocated (at least 4GB recommended). + +## Security Considerations + +### Root Access +**Problem**: Concerned about running with root access. + +**Solution**: This container is designed to run as the `tsysdevstack` user with no root access at runtime. The only root usage is during the build process for installing system packages. + +### Network Security +**Problem**: Need to run without network access. + +**Solution**: The container can run offline once built. It can perform all document generation tasks without network access, though some features like fetching remote templates or themes would be unavailable. + +### File Access +**Problem**: Container can access files it shouldn't. + +**Solution**: The container only has access to files in the `/docs` and `/output` directories that you explicitly mount. Files outside these directories are not accessible. \ No newline at end of file diff --git a/toolbox-docs/documentation/USAGE.md b/toolbox-docs/documentation/USAGE.md new file mode 100644 index 0000000..e266290 --- /dev/null +++ b/toolbox-docs/documentation/USAGE.md @@ -0,0 +1,176 @@ +# Usage Guide - TSYS Dev Stack Docs Toolbox + +## Table of Contents +- [Overview](#overview) +- [Running the Container](#running-the-container) +- [Available Tools](#available-tools) +- [Document Conversion Workflows](#document-conversion-workflows) +- [Development Workflows](#development-workflows) + +## Overview + +The TSYS Dev Stack Docs Toolbox is a comprehensive document production environment with all the tools you need to create beautiful documents from various source formats. This container runs as the `tsysdevstack` user with no root access, ensuring security while providing a powerful document creation toolkit. + +## Running the Container + +### Using the Run Script +```bash +# Run interactively (default) +./run.sh + +# Run in detached mode +./run.sh -d + +# Build the image first, then run +./run.sh -b + +# Build and run in detached mode +./run.sh -b -d +``` + +### Using Docker Compose +```bash +# Run the container with docker-compose +docker-compose up + +# Run and build if needed +docker-compose up --build + +# Run in detached mode +docker-compose up -d +``` + +### Direct Docker Run +```bash +# Run with direct docker command +docker run -it --rm \ + -v $(pwd)/docs:/home/tsysdevstack/docs \ + -v $(pwd)/output:/home/tsysdevstack/output \ + tsysdevstack/toolbox-docs:latest +``` + +## Available Tools + +### Pandoc +Convert documents between various formats with powerful templating capabilities: +```bash +pandoc input.md -o output.pdf +pandoc input.md -o output.docx +pandoc input.md -o output.html +``` + +### MdBook +Create books and documentation sites from markdown files: +```bash +# Build a book +mdbook build + +# Serve a book locally with live reload +mdbook serve + +# Create a new book +mdbook init mybook +``` + +### Typst +Modern typesetting tool for scientific and technical documents: +```bash +# Compile a typst document +typst compile document.typ document.pdf + +# Watch for changes and recompile +typst watch document.typ +``` + +### Marp +Create slide decks from markdown: +```bash +# Convert markdown to PDF slides +marp --pdf slides.md + +# Convert to HTML +marp --html slides.md + +# Serve slides with live preview +marp --server slides.md +``` + +### Quarto +Next generation scientific and technical publishing system: +```bash +# Render a document +quarto render document.qmd + +# Convert to PDF +quarto render document.qmd --to pdf + +# Create a new project +quarto create-project myproject --type book +``` + +### JQ/YQ +Process JSON and YAML files: +```bash +# Format JSON +jq '.' data.json + +# Extract values from JSON +jq '.field' data.json + +# Process YAML files +yq '.field' data.yml +``` + +## Document Conversion Workflows + +### Markdown to Professional PDF +Convert markdown documents to professionally formatted PDFs: +```bash +# For resumes (ATS optimized) +pandoc resume.md -o resume.pdf --template=altacv + +# For project plans and proposals +pandoc document.md -o document.pdf --template=eisvogel +``` + +### Joplin Notes to PDF +Export your Joplin notes with full formatting preserved: +```bash +# Export individual notes +pandoc joplin_note.md -o note.pdf --css=styles.css + +# For complex formatting use a custom template +pandoc joplin_note.md -o note.pdf --template=custom.latex +``` + +### Creating Books with mdBook +Organize content into structured books: +```bash +# Initialize a new book +mdbook init my-book + +# Build the book in output directory +mdbook build + +# Preview with live reload +mdbook serve --open +``` + +## Development Workflows + +### Local Development +1. Mount your source files to `/home/tsysdevstack/docs` in the container +2. Place output files in `/home/tsysdevstack/output` which is also mounted +3. Use the container interactively for development +4. Run `mdbook serve` for live preview during content development + +### CI/CD Pipeline +1. Build the container with your content inside +2. Run conversion tools to generate all document formats +3. Extract output files from the container +4. Deploy or package as needed + +### Version Control +- Keep source files (markdown, typst, etc.) in version control +- Exclude generated files (PDFs, HTML, etc.) from version control +- Use docker-compose for consistent development environments across teams \ No newline at end of file diff --git a/toolbox-docs/examples/README.md b/toolbox-docs/examples/README.md new file mode 100644 index 0000000..9ffd17d --- /dev/null +++ b/toolbox-docs/examples/README.md @@ -0,0 +1,60 @@ +# Examples Directory + +This directory contains example documents and workflow scripts to help you get started with the TSYS Dev Stack Docs Toolbox. + +## Table of Contents +- [Markdown Examples](#markdown-examples) +- [Book Examples](#book-examples) +- [Presentation Examples](#presentation-examples) +- [Workflow Scripts](#workflow-scripts) + +## Markdown Examples + +### Resume Example +- `resume-example.md` - A sample resume in markdown format optimized for ATS systems +- `resume-example.pdf` - The generated PDF version using pandoc + +### Technical Documentation +- `technical-doc.md` - A sample technical document with code blocks and diagrams +- `technical-doc.pdf` - The generated PDF with proper formatting +- `technical-doc.html` - The generated HTML version + +### Joplin Notes Conversion +- `joplin-note-example.md` - Sample Joplin note with formatting +- `joplin-note-example.pdf` - Converted PDF preserving Joplin formatting + +## Book Examples + +### Simple Book +- `simple-book/` - A complete mdBook project with: + - `book.toml` - Configuration file + - `src/SUMMARY.md` - Table of contents + - `src/chapter_1.md` - First chapter + - `src/chapter_2.md` - Second chapter + +### Technical Book +- `technical-book/` - A more complex mdBook project with: + - Custom CSS styling + - Code examples with syntax highlighting + - Diagrams and images + +## Presentation Examples + +### Marp Slides +- `marp-slides-example.md` - Slides created with Marp syntax +- `marp-slides-example.pdf` - Exported PDF slides + +### Quarto Presentation +- `quarto-slides-example.qmd` - Presentation in Quarto format +- `quarto-slides-example.html` - Generated reveal.js presentation + +## Workflow Scripts + +### Document Generation Workflow +- `generate-resume.sh` - Complete workflow to convert markdown resume to PDF +- `generate-docs.sh` - Workflow to convert multiple markdown documents to various formats +- `generate-book.sh` - Workflow to build and package an entire mdBook project + +### Batch Processing +- `batch-convert.py` - Python script to batch convert multiple documents +- `convert-to-all-formats.sh` - Script to generate all format variants of a document \ No newline at end of file diff --git a/toolbox-docs/examples/generate-resume.sh b/toolbox-docs/examples/generate-resume.sh new file mode 100644 index 0000000..5fdc034 --- /dev/null +++ b/toolbox-docs/examples/generate-resume.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash + +# Workflow script to convert markdown resume to PDF using pandoc +set -e + +INPUT_FILE="resume-example.md" +OUTPUT_FILE="resume-example.pdf" +TEMPLATE="altacv" + +echo "Converting resume to PDF..." + +# Check if input file exists +if [ ! -f "$INPUT_FILE" ]; then + echo "Error: Input file '$INPUT_FILE' does not exist." + exit 1 +fi + +# Convert using pandoc with altacv template for ATS-optimized resume +pandoc "$INPUT_FILE" \ + -o "$OUTPUT_FILE" \ + --template="$TEMPLATE" \ + --pdf-engine=xelatex \ + --variable "geometry:margin=0.5in" \ + --variable "colorlinks:true" \ + --variable "linkcolor:blue" \ + --variable "urlcolor:blue" + +if [ $? -eq 0 ]; then + echo "Resume successfully converted to '$OUTPUT_FILE'" +else + echo "Error: Failed to convert resume" + exit 1 +fi \ No newline at end of file diff --git a/toolbox-docs/examples/resume-example.md b/toolbox-docs/examples/resume-example.md new file mode 100644 index 0000000..ccb885f --- /dev/null +++ b/toolbox-docs/examples/resume-example.md @@ -0,0 +1,47 @@ +# Example Resume in Markdown + +--- +title: "John Doe" +author: [] +date: [] +output: + pdf_document: + template: altacv + pandoc_args: ["--top-level-division=section"] +--- + +# Personal Info + +**Address:** 123 Main St, City, State +**Phone:** (555) 123-4567 +**Email:** john.doe@example.com +**LinkedIn:** [johndoe](https://linkedin.com/in/johndoe) + +# Experience + +## Senior Software Engineer +**Tech Company** | Jan 2022 - Present +- Led development of microservices architecture that improved system scalability by 40% +- Mentored junior developers and conducted technical interviews +- Implemented CI/CD pipelines reducing deployment time by 60% + +## Software Engineer +**Previous Company** | Jun 2019 - Dec 2021 +- Developed and maintained RESTful APIs serving 10K+ daily active users +- Collaborated with cross-functional teams to deliver product features +- Optimized database queries resulting in 25% improvement in response times + +# Education + +## Master of Science in Computer Science +**University Name** | 2017 - 2019 + +## Bachelor of Science in Software Engineering +**University Name** | 2013 - 2017 + +# Skills + +- **Languages:** JavaScript, Python, Go, Rust, Java +- **Frameworks:** React, Node.js, Django, Spring Boot +- **Technologies:** Docker, Kubernetes, AWS, PostgreSQL, Redis +- **Tools:** Git, Jenkins, Jira, Confluence \ No newline at end of file diff --git a/toolbox-docs/examples/technical-doc.md b/toolbox-docs/examples/technical-doc.md new file mode 100644 index 0000000..38f1d61 --- /dev/null +++ b/toolbox-docs/examples/technical-doc.md @@ -0,0 +1,124 @@ +# Technical Documentation Example + +## Introduction + +This is a sample technical document to demonstrate the capabilities of the TSYS Dev Stack Docs Toolbox. This document includes various elements that are commonly found in technical documentation. + +## Code Examples + +Here's a Python example with syntax highlighting: + +```python +def fibonacci(n): + """ + Generate the first n numbers in the Fibonacci sequence. + + Args: + n (int): Number of Fibonacci numbers to generate + + Returns: + list: List containing the first n Fibonacci numbers + """ + if n <= 0: + return [] + elif n == 1: + return [0] + elif n == 2: + return [0, 1] + + fib_sequence = [0, 1] + for i in range(2, n): + next_num = fib_sequence[i-1] + fib_sequence[i-2] + fib_sequence.append(next_num) + + return fib_sequence + +# Example usage +print(fibonacci(10)) # Output: [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] +``` + +And here's a JavaScript example: + +```javascript +class TodoList { + constructor() { + this.tasks = []; + } + + addTask(task) { + this.tasks.push({ + id: Date.now(), + text: task, + completed: false + }); + } + + completeTask(id) { + const task = this.tasks.find(t => t.id === id); + if (task) { + task.completed = true; + } + } +} +``` + +## Configuration Examples + +Here's a sample configuration in YAML: + +```yaml +server: + port: 8080 + host: "0.0.0.0" + timeout: 30s + +database: + host: "localhost" + port: 5432 + name: "myapp" + ssl: true + +logging: + level: "info" + format: "json" + output: "stdout" +``` + +## Diagrams + +The following diagram would be generated using Kroki or similar tools: + +``` +graph TD + A[Client] --> B[Load Balancer] + B --> C[Web Server 1] + B --> D[Web Server 2] + B --> E[Web Server 3] + C --> F[Database] + D --> F + E --> F +``` + +## Tables + +| Feature | Status | Priority | +|--------|--------|----------| +| User Authentication | Complete | High | +| Data Export | In Progress | High | +| Reporting | Planned | Medium | +| Dashboard | Complete | High | + +## Mathematical Notation + +The quadratic formula: $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ + +Maxwell's equations: + +$$\nabla \cdot \vec{E} = \frac{\rho}{\varepsilon_0}$$ +$$\nabla \cdot \vec{B} = 0$$ +$$\nabla \times \vec{E} = -\frac{\partial B}{\partial t}$$ +$$\nabla \times \vec{B} = \mu_0\left(\vec{J} + \varepsilon_0\frac{\partial E}{\partial t}\right)$$ + +## Conclusion + +This document demonstrates various features available in the documentation toolbox. You can convert this to PDF, Word, or HTML formats using Pandoc and other tools. \ No newline at end of file diff --git a/toolbox-docs/run.sh b/toolbox-docs/run.sh new file mode 100755 index 0000000..c7f6af6 --- /dev/null +++ b/toolbox-docs/run.sh @@ -0,0 +1,103 @@ +#!/usr/bin/env bash + +# Script to run the tsysdevstack-toolboxes-docs container +set -e + +# Default values +CONTAINER_NAME="tsysdevstack-toolboxes-docs" +IMAGE_NAME="tsysdevstack/toolbox-docs:latest" +WORKDIR="/home/tsysdevstack/docs" + +# Function to display usage +usage() { + echo "Usage: $0 [OPTIONS]" + echo "Options:" + echo " -i, --interactive Run container interactively (default)" + echo " -b, --build Build the image before running" + echo " -d, --detached Run container in detached mode" + echo " -h, --help Show this help message" + echo "" + echo "Examples:" + echo " $0 # Run interactively (default)" + echo " $0 -d # Run in detached mode" + echo " $0 -b # Build image and run" + echo " $0 -b -d # Build image and run in detached mode" +} + +# Parse command line arguments +INTERACTIVE=true +DETACHED=false +BUILD=false + +while [[ $# -gt 0 ]]; do + case $1 in + -i|--interactive) + INTERACTIVE=true + shift + ;; + -d|--detached) + DETACHED=true + INTERACTIVE=false + shift + ;; + -b|--build) + BUILD=true + shift + ;; + -h|--help) + usage + exit 0 + ;; + *) + echo "Unknown option: $1" + usage + exit 1 + ;; + esac +done + +# If both interactive and detached are false, default to interactive +if [ "$INTERACTIVE" = true ] && [ "$DETACHED" = false ]; then + # Default behavior remains interactive + : +fi + +# Build the image if requested +if [ "$BUILD" = true ]; then + echo "Building the Docker image..." + docker build -t "$IMAGE_NAME" . +fi + +# Prepare docker run command +DOCKER_RUN_CMD="docker run --rm" + +# Add user mapping to match host user +if [ -n "${UID:-}" ] && [ -n "${GID:-}" ]; then + DOCKER_RUN_CMD="$DOCKER_RUN_CMD --user $UID:$GID" +else + # Fallback to default user ID + DOCKER_RUN_CMD="$DOCKER_RUN_CMD --user 1000:1000" +fi + +# Add volume mounts +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +DOCKER_RUN_CMD="$DOCKER_RUN_CMD -v $SCRIPT_DIR/docs:$WORKDIR" +DOCKER_RUN_CMD="$DOCKER_RUN_CMD -v $SCRIPT_DIR/output:/home/tsysdevstack/output" + +# Add container name +DOCKER_RUN_CMD="$DOCKER_RUN_CMD --name $CONTAINER_NAME" + +# Add detached mode flag if requested +if [ "$DETACHED" = true ]; then + DOCKER_RUN_CMD="$DOCKER_RUN_CMD -d" +else + # Add interactive and TTY flags for interactive mode + DOCKER_RUN_CMD="$DOCKER_RUN_CMD -it" +fi + +# Add image name +DOCKER_RUN_CMD="$DOCKER_RUN_CMD $IMAGE_NAME" + +# Run the container +echo "Running: $DOCKER_RUN_CMD" +eval "$DOCKER_RUN_CMD" \ No newline at end of file diff --git a/toolbox-docs/test.sh b/toolbox-docs/test.sh new file mode 100755 index 0000000..365e7bd --- /dev/null +++ b/toolbox-docs/test.sh @@ -0,0 +1,122 @@ +#!/usr/bin/env bash + +# Script to test the tsysdevstack-toolboxes-docs container +set -e + +# Default values +IMAGE_NAME="tsysdevstack/toolbox-docs:latest" +CONTAINER_NAME="tsysdevstack-toolboxes-docs-test" +WORKDIR="/home/tsysdevstack/docs" + +echo "Starting tests for tsysdevstack-toolboxes-docs container..." + +# Function to run a command in the container and check the exit code +run_test() { + local test_name="$1" + local command="$2" + local expected_result="${3:-0}" # Default expected result is 0 (success) + + echo "Running test: $test_name" + echo "Command: $command" + + # Run the command in the container + if docker run --rm --name "${CONTAINER_NAME}-$(date +%s%N)" "$IMAGE_NAME" bash -c "$command"; then + if [ "$expected_result" -eq 0 ]; then + echo "✓ PASS: $test_name" + else + echo "✗ FAIL: $test_name - Expected failure but command succeeded" + return 1 + fi + else + if [ "$expected_result" -ne 0 ]; then + echo "✓ PASS: $test_name - Command failed as expected" + else + echo "✗ FAIL: $test_name - Command failed unexpectedly" + return 1 + fi + fi + echo "" +} + +# Test 1: Check if user is tsysdevstack +run_test "User verification" "whoami | grep tsysdevstack" + +# Test 2: Check if required tools are installed +run_test "Pandoc installation" "pandoc --version" +run_test "MdBook installation" "mdbook --version" +run_test "Typst installation" "typst --version" +run_test "Marp CLI installation" "marp --version" +run_test "Quarto installation" "quarto --version" +run_test "YQ installation" "yq --version" +run_test "JQ installation" "jq --version" +run_test "Vale installation" "vale --version" +run_test "BibTool installation" "bibtool -h" +run_test "Wkhtmltopdf installation" "wkhtmltopdf --version" +run_test "Joplin installation" "npm list -g joplin || echo 'joplin not found via npm'" + +# Test 3: Check if Python is available via mise +run_test "Python via mise" "mise exec -- python --version" + +# Test 4: Check if Node.js is available via mise +run_test "Node.js via mise" "mise exec -- node --version" + +# Test 5: Check if Rust is available via mise +run_test "Rust via mise" "mise exec -- rustc --version" + +# Test 6: Check if Ruby is available via mise +run_test "Ruby via mise" "mise exec -- ruby --version" + +# Test 7: Check if TeXLive is properly installed +run_test "TeXLive installation" "pdflatex --version" + +# Test 8: Check if Git is available +run_test "Git installation" "git --version" + +# Test 9: Check if shells are available +run_test "Fish shell installation" "fish --version" +run_test "Zsh installation" "zsh --version" +run_test "Bash installation" "bash --version" + +# Test 10: Check if Mise is working properly +run_test "Mise activation" "source ~/.bashrc && mise --version" + +# Test 11: Test basic functionality - convert markdown to PDF with Pandoc +echo "Running advanced test: Pandoc markdown to PDF conversion" +cat << 'EOF' > /tmp/test.md +% Test Document +% Test Author + +# Introduction + +This is a test document to verify that Pandoc is working correctly. + +## Features + +- Pandoc conversion +- Markdown formatting +- PDF generation + +### Code Block Example + +```python +def hello(): + print("Hello, World!") +``` + +EOF + +# Run a simple conversion test inside the container +if docker run --rm -v /tmp:/tmp -w /tmp "$IMAGE_NAME" bash -c "pandoc test.md -o test.pdf"; then + echo "✓ PASS: Pandoc conversion test" + # Clean up the generated file + rm -f /tmp/test.pdf +else + echo "✗ FAIL: Pandoc conversion test" + exit 1 +fi +echo "" + +# Test 12: Check if the working directory exists +run_test "Working directory exists" "test -d $WORKDIR" + +echo "All tests completed successfully!" \ No newline at end of file