How llsoftsec/llsoftsecbook works
Main Components
• Content Sources:
• The core book content is contained within files like book.md and its associated bibliography file (book.bib).
• Supporting media (e.g., images) reside in the img folder.
• Theme & Styling:
• The “theme” directory holds templates and styles for different output formats: subdirectories for HTML (with various Lua filters and CSS files), EPUB (with custom CSS), and TeX (for PDF generation via pandoc_template.tex).
• Build & Processing Infrastructure:
• Build scripts: Makefile (which calls “make all”) and build_with_docker.sh/.bat that ensure builds run in a controlled Docker container environment.
• Docker: The docker folder includes a Dockerfile and entrypoint.sh which define the containerized environment to install specific versions of Pandoc, LaTeX, and required packages.
• The .mlc_config.json and other configuration files help control build parameters.
• Continuous Integration / Version Control:
• The .github/workflows folder contains CI/CD scripts (e.g., main.yml) that likely automate the build process, test contributions, and help publish outputs (e.g., via GitHub pages).
• Files like .gitignore, CODE_OF_CONDUCT.md, LICENSE, and contributing.md indicate robust community and collaboration practices.
Establishing Relationships and Workflows
• Source-to-Build Flow:
• The main markdown content (book.md) and its supporting bibliography (book.bib) along with images are processed using pandoc and LaTeX. This processing relies on styling templates provided in the theme folder.
• Build Orchestration:
• The Makefile serves as the orchestrator for the book build, invoking either local or Dockerized builds.
• The Docker container (configured via docker/Dockerfile and entrypoint.sh) encapsulates the required environment to guarantee consistent builds.
• Deployment and Automation:
• GitHub workflows kick off builds on code changes or pull requests, ensuring that the outputs (HTML, PDF) are up-to-date and testing the integrity of the build process.
Technologies and Tools
• Pandoc – used for converting markdown to various formats.
• LaTeX – integrated when generating the PDF version.
• Docker – for containerizing the build environment.
• GitHub Actions – for continuous integration and automated builds.
• Make – for build orchestration.
Detail
• Relationship between the configuration (like .mlc_config.json and Makefile directives) and the build pipeline.
• That the automation via GitHub workflows ensures ongoing integration with contributions from the community.