linkorb / blazon
Blazon: publish fast and beautiful websites, campaign sites, documentation, guides etc from data (e.g. Xillion Resources)
Installs: 9
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 1
Open Issues: 3
Type:application
Requires
- php: >=7.2.0
- guzzlehttp/guzzle: ^7.4
- laminas/laminas-diactoros: ^2.6
- league/commonmark: ^2.3
- league/container: ^4.0
- league/event: ^3.0
- linkorb/xillion: ^1.8
- monolog/monolog: ^2.3
- symfony/console: ^5.2
- symfony/dotenv: ^5.0
- symfony/yaml: ^5.0
- twig/twig: ^1.0
Requires (Dev)
- linkorb/autotune: ^1.0
This package is not auto-updated.
Last update: 2024-11-19 09:37:14 UTC
README
blazon
Blazon is a data-driven, plugin-powered, multi-target content publishing framework.
Use-cases:
- Documentation, guides, manuals
- Contracts (with variables)
- Legal documents
- "Conditional text" content
- Wiki content rendering
- Marketing sites
- Policies, Procedures, Forms
- Knowledge graphs
- Digital gardens
- Code repository project documentation
- Complex data graph visualization (i.e. organizational structures)
Definitions:
- Publication: Collection of "documents"
- Document: unique identifier (path), and a controller for rendering output
- Plugin: allows to modify every phase of the loading and publishing process
- Target: one of many outputs, produced by a Publisher (i.e. static html, pdf, etc).
Features:
- Load content from local or remote sources
- Markdown, with frontmatter
- Xillion Resources
- Twig templating
- Supports both static site generation and dynamic rendering
Examples
- https://github.com/linkorb/starwars-blazon graphql + twig example site
Installation
git clone git@github.com:linkorb/blazon.git cd blazon composer install # install php dependencies into blazon's vendor/ directory ./bin/blazon -v # get version and help output
Usage
Your Blazon project (i.e. your site, book, report, etc) should be stored in it's own directory, preferably a Git repository.
From there, use the blazon
cli tool to generate a static HTML site into the build/
directory of your project:
Publishing
cd path/to/my/blazon-project
path/to/blazon publish -vvv
This command:
- Builds your Publication in-memory, using your custom
PublicationFactory
, or the default factory. - Loops over all registered
Document
instances - Renders the output of each
Document
using it'shandler
callback, and writes it to the Document'spath
intobuild/
- Recursively copies any public assets (images, css, js, pdfs, etc) from
public/
intobuild/
You can now serve the generated build/
directory as a static (html) site on your favorite service:
- A simple nginx container
- Github pages
- Netlify
- ...etc
Auto-Publishing with "watch-mode"
Pass the -w
flag to the blazon publish
command to tell blazon to keep watching your project's source directory for changes. After any detected change, it will automatically (re)publish to build/
Preview server
Blazon includes a minimal preview server that you can use while authoring content and styling your publication.
Simply point your favorite PHP-enabled webserver (i.e. apache with mod-php, nginx with php-fpm, etc) to blazon's public/
directory.
Make sure to setup SOURCE_PATH=/path/to/your/blazon-project
in Blazon's .env
file.
Features:
- Builds the publication on every HTTP request
- In-memory, no writes to
build/
- Verbose error messages when setting
DEBUG=true
in your.env
file. - Supports serving static assets from your publication's
public/
directory.
It is not recommended to use the preview server in production. Use the blazon publish
command instead for maximum security and performance.
Inspiration
- Gatsby
- Hugo
- Sage
- Xillion
- Schemata
Contributing
We welcome contributions to make this repository even better. Whether it's fixing a bug, adding a feature, or improving documentation, your help is highly appreciated. To get started, fork this repository then clone your fork.
Be sure to familiarize yourself with LinkORB's Contribution Guidelines for our standards around commits, branches, and pull requests, as well as our code of conduct before submitting any changes.
If you are unable to implement changes you like yourself, don't hesitate to open a new issue report so that we or others may take care of it.
Brought to you by the LinkORB Engineering team
Check out our other projects at linkorb.com/engineering.
By the way, we're hiring!