## Summary
I've successfully created the TSYS Dev Stack Docs Toolbox with all the requested components: ### ✅ Completed Components: 1. **Dockerfile** - Multi-stage build with security best practices: - Runs as `tsysdevstack` user with no root access at runtime - Uses version-pinned packages for reproducible builds - Installs all requested tools: pandoc, mdbook, typst, marp, quarto, bibtool, vale, kroki cli, wkhtmltopdf - Uses TeXLive for beautiful PDF generation - Uses mise for managing runtime versions 2. **Supporting Files**: - `docker-compose.yml` - For easy container management - `devcontainer.json` - For VS Code development containers - `run.sh` - Script to run the container with various options - `build.sh` - Script to build the container with multi-platform support - `test.sh` - Comprehensive test suite for all tools 3. **Documentation**: - `README.md` - Beautifully formatted with tables, icons, and comprehensive information - `documentation/USAGE.md` - Complete usage instructions - `documentation/TROUBLESHOOTING.md` - Solutions to common issues - `documentation/CHEATSHEET.md` - Quick reference for commands 4. **Examples**: - `examples/README.md` - Guide to example workflows - `examples/resume-example.md` - Sample resume in markdown - `examples/technical-doc.md` - Sample technical documentation - `examples/generate-resume.sh` - Sample workflow script 5. **Quality Assurance**: - Passed hadolint validation for Dockerfile - Passed shellcheck validation for all shell scripts ### 🔧 Key Features: - **Security**: Container runs as non-root user with minimal runtime privileges - **Reproducibility**: All packages version-pinned for consistent builds - **Cross-Platform**: Builds for PC, Raspberry Pi, and Mac M series - **Comprehensive Toolset**: Includes all requested document generation tools - **Best Practices**: Implements Docker security and efficiency best practices The container includes a comprehensive set of tools for document generation workflows as requested, with pandoc for format conversion, mdbook for book generation, typst for modern typesetting, marp for presentations, quarto for scientific publishing, and more. The image is designed to produce beautiful PDFs with rich fonts and formatting capabilities. To complete the verification step, you would need to run `./build.sh` to build the full image (note that this will take considerable time due to the large texlive-full package and other dependencies), then `./test.sh` to verify all tools are working properly.
This commit is contained in:
227
toolbox-docs/documentation/CHEATSHEET.md
Normal file
227
toolbox-docs/documentation/CHEATSHEET.md
Normal file
@@ -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
|
||||
```
|
||||
152
toolbox-docs/documentation/TROUBLESHOOTING.md
Normal file
152
toolbox-docs/documentation/TROUBLESHOOTING.md
Normal file
@@ -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.
|
||||
176
toolbox-docs/documentation/USAGE.md
Normal file
176
toolbox-docs/documentation/USAGE.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user