PHPackages sumpygump/holograph - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. sumpygump/holograph ActiveUtility[Utility & Helpers](/categories/utility) sumpygump/holograph =================== Style guide build tool 1.0(6y ago)623MITPHPPHP >=5.3CI failing Since Aug 19Pushed 4y ago2 watchersCompare [ Source](https://github.com/sumpygump/holograph)[ Packagist](https://packagist.org/packages/sumpygump/holograph)[ RSS](/packages/sumpygump-holograph/feed)WikiDiscussions master Synced 3w ago READMEChangelogDependencies (5)Versions (9)Used By (0) Holograph ========= [](#holograph) Holograph is a tool for managing the CSS documentation of a project, with specific features that enable one to create and maintain a decent CSS style guide. It is written in PHP and is similar to [hologram](https://github.com/trulia/hologram)and [Knyle Style Sheets](http://warpspire.com/posts/kss/). Features -------- [](#features) - Composable. Just drop in a require to your composer.json file and start running holograph. - Use as a build tool to generate a style guide as well as minify and combine CSS files. Installation ------------ [](#installation) ### Using Composer [](#using-composer) Add the following to your `composer.json` file: ``` { "require": { "sumpygump/holograph": "dev-master" } } ``` Then run composer install to fetch. ``` $ composer.phar install ``` If you don't have composer already installed, this is my recommendation for installing it. See [getcomposer.org installation instructions](http://getcomposer.org/doc/00-intro.md#globally). ``` $ curl -sS https://getcomposer.org/installer | php $ sudo mv composer.phar /usr/local/bin/composer ``` Once installed, there is a CLI command in `vendor/bin/holograph`. The easiest way to use holograph is to ensure that `./vendor/bin` is added to your system's `$PATH`. ``` $ export PATH=$PATH:./vendor/bin ``` #### Global Installation using Composer [](#global-installation-using-composer) An alternate way to install holograph so it is available on any project is by installing it in your `~/.composer` directory using the following command: ``` composer global require 'sumpygump/holograph=dev-master' ``` You must have `~/.composer/vendor/bin` in your environment PATH. ``` $ export PATH=$PATH:~/.composer/vendor/bin ``` Usage ----- [](#usage) The basic feature of holograph is to generate a style guide based on comments added in your CSS files. Additional Markdown files can also be added to create the styleguide's documentation. CSS Files --------- [](#css-files) The first step in getting use out of Holograph is to format comments blocks in your CSS stylesheets. Add document blocks in your CSS files with some YAML and some markdown as documented below. ``` /*doc --- name: badgeSkins --- Badges are a way to display a small amount of text or an image within a nicely formatted box. Class | Description -------------- | ----------------- badgeStandard | This is a basic badge badgePrimary | This is a badge with the trulia orange used on CTAs badgeSecondary | This is a badge with the alternate CTA color (Trulia green) badgeTertiary | This is a badge for a warning or something negative ```html_example Sold For Sale For Rent ``` */ .badgeStandard { background-color: #999999; } .badgePrimary { background-color: #ff5c00; } .badgeSecondary { background-color: #5eab1f; } ``` ### Document Blocks [](#document-blocks) Any comment block starting with `/*doc` will be considered a document block, and will be inspected and parsed by the styleguide generator. ``` /*doc This is my document block. */ ``` ### YAML Matter [](#yaml-matter) A document block must have a YAML block at the top of the comment surrounded by lines with three dashes (`---`). YAML is a convenient way to store key-value pairs. The YAML block must contain at a minimum the `name` key. ``` /*doc --- name: media-object --- */ ``` YAML block key-value pairs consist of a key name on the left followed by a colon, a space, and then the value. For example: `name: button` The following document block YAML keys are used by Holograph: KeyMeaningtitleThe title for this componentnameA unique name for this component (required)categoryWhich category this component appears, in the main navigationparentThe name of the parent's component, to define this component as a childFull example: ``` /*doc --- title: Badge Colors parent: badge name: badgeSkins category: Components --- */ ``` The `title` of the component is used when displaying the heading for that component's documentation. All components of a given `category` will be put into an HTML file with the same name as the category. Using the default layout template (see below), each category HTML file will be accessible in the main navigation of the outputed styleguide. Note: If no category is provided, holograph will default the category to `index` and thus the component documenation will be placed into `index.html` of the rendered styleguide. If a component is a `parent` (has child components), it will be displayed first, followed by its child components on the rendered category page. Example of parent/child definition: ``` /*doc --- name: badge --- */ /*doc --- name: badgeSkins parent: badge --- */ ``` The above example defines a component named "badge" and a child component named "badgeSkins." The badgeSkins documentation will be placed below the badge documentation. ### HTML code examples [](#html-code-examples) If your markdown documentation in your document blocks contains an fenced code block with the type `html_example`, Holograph will output the sample HTML and the HTML code in the styleguide. This provides a great way to document and showcase example usage of your CSS classes. Example: ``` ```html_example Click ``` ``` Markdown Files -------------- [](#markdown-files) You can also place Markdown files in the source directory. These files will be processed and included in the destination directory. Markdown files (\*.md) will be renamed to \*.html. For example `overview.md` will be renamed to `overview.html` when included in the destination directory. Each markdown file will also be added to the main navigation rendered to the styleguide. Note: Holograph includes the [extra-extended](https://github.com/egil/php-markdown-extra-extended)flavor of Markdown syntax, which suppors markdown syntax such as fenced code blocks and tables. Configuration ------------- [](#configuration) Holograph uses a configuration file to define paths and other aspecst for the current directory's build parameters. The default name for the configuration file is `holograph.yml`. Holograph looks for a file of this name in the current directory when building. The following is the default config file. ``` # Holograph configuration # The title for this styleguide {{title}} title: 'Style Guide' # The directory containing the source files to parse source: ./components # The directory to generate files to destination: ./docs # Directory location of assets needed to accompany the docs (layout.html) documentation_assets: ./templates # Boolean indicating whether to use hologram compatibility # When true it will expect header.html and footer.html instead of layout.html compat_mode: false # Any other asset folders that need to be copied to the destination folder dependencies: - ./build # Build option to actually compiles CSS files (options: none, minify) preprocessor: minify # Directory to build the final CSS files build: ./build/css # The main stylesheet to be included {{main_stylesheet}} main_stylesheet: build/css/screen.css ``` ### File paths [](#file-paths) Here is an explanation of the file paths in the config file. PathExplanationsourceThe source path is a directory where the subject CSS and Markdown files residedestinationThe destination path is where the styleguide will be writtendocumentation\_assetsThis is a path where the template files and styles for the styleguide itself are keptdependenciesDependencies is an array of multiple paths, the contents of which should also``` | be copied to the destination directory. Example: fonts, images used by the examples. ``` build | The build path is where the preprocessor will write its output file(s). ### Documentation Assets [](#documentation-assets) The documentation assets provides template files and CSS files used to render the structure of the styleguide. By default, Holograph looks for a file called `layout.html` in the documenation\_assets directory. If none is found it will use the default layout file in the `default-templates` directory in the Holograph install directory. The `layout.html` file can contain the following tokens that will be replaced during the build step: - `{{title}}` - This will be replaced with the title defined in the config file - `{{main_stylesheet}}` - This will be replaced with the path to the stylesheet generated by the preprocessor and represents the styles you are wishing to document with the styleguide. - `{{navigation}}` - This will be replaced with a `` of the generated HTML files (categories) - `{{content}}` - This will be replaced with the content of the styleguide documentation. You are encouraged to create a style guide layout file that will fit with your site's branding or design. Any subfolders in the `documentation_assets` will also be copied into the destination folder so you can include assets like fonts, images, css and javascript to be used by the styleguide layout. Running holograph ----------------- [](#running-holograph) Holograph can be run from the command line ``` $ holograph Holograph 0.7 A markdown based build and documentation system for OOCSS Usage: holograph [OPTIONS] Actions: init : Initialize environment for holograph (write conf file with defaults) config : Show current configuration parameters build : Build the style guide HTML/CSS help : Display program help and exit Options: -c | --conf : Use alternate configuration file -h | --help : Display program help and exit -q | --quiet : Quiet mode (Don't output anything) -v | --verbose : Verbose output mode --version : Display program version and exit --compat : Use hologram compatible mode (header.html/footer.html) ``` ### init [](#init) An easy way to create a clean `holograph.yml` config file in the current directory is to run the `holograph init` command. ### config [](#config) Running `holograph config` will display the current configuration parameters in the config file of the current directory. ### build [](#build) To build the styleguide from the source \*.css and \*.md files, run `holograph build`. This will complete the following tasks: 1. read the config file 2. run the preprocessor (optimization step) 3. parse the CSS and Markdown files 4. generate the styleguide HTML files 5. copy the documentation assets and any other defined dependencies into the destination directory. The Preprocessor ---------------- [](#the-preprocessor) The preprocessor is a mechanism to run a optimization step prior to building the styleguide documentation. The current version only supports the options `minify`or `none`. The "minify" option will use [Minify](https://github.com/mrclay/minify)to minify the CSS files within the source directory and then combine them into one file. This is currently a limited operation. It is expected that this functionality will be expanded to support more complex configurations and other optimization engines such as Sass or Less. The following settings in the config file are used by the preprocessor: ``` preprocessor: minify ``` The "preprocessor" key provides a directive of which minify option to use. Currently the options are "minify" or "none". ``` build: ./build/css ``` The "build" key defines a directory where the final optimized CSS file should be written. ``` main_stylesheet: build/css/screen.css ``` The "main\_stylesheet" is the file path and name the preprocessor uses as the final output file for the optimized stylesheet. This value is also used to include the destination stylesheet in the styleguide build output. ### Health Score 29 — LowBetter than 57% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity12 Limited adoption so far Community8 Small or concentrated contributor base Maturity63 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~336 days Recently: every ~589 days Total 8 Last Release 2342d ago Major Versions 0.9 → 1.02020-02-02 ### Community Maintainers ![](https://www.gravatar.com/avatar/a84a7eefd7bc45723fd004f1424c6183557eea2b82cc7265c739b753cb34d1cf?d=identicon)[sumpygump](/maintainers/sumpygump) --- Top Contributors [![sumpygump](https://avatars.githubusercontent.com/u/676007?v=4)](https://github.com/sumpygump "sumpygump (47 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/sumpygump-holograph/health.svg) ``` [![Health](https://phpackages.com/badges/sumpygump-holograph/health.svg)](https://phpackages.com/packages/sumpygump-holograph) ``` ### Alternatives [kimai/kimai Kimai - Time Tracking 4.8k9.0k1](/packages/kimai-kimai)[friendsoftypo3/content-blocks TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML 103519.9k48](/packages/friendsoftypo3-content-blocks)[rcsofttech/audit-trail-bundle Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking. 1189.8k](/packages/rcsofttech-audit-trail-bundle)[altis/local-server Local Server module for Altis 18221.6k3](/packages/altis-local-server)[2lenet/crudit-bundle The easy like Crud'it Bundle. 1616.4k12](/packages/2lenet-crudit-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)