{"id":23893315,"url":"https://github.com/sumpygump/holograph","last_synced_at":"2025-04-10T12:51:59.543Z","repository":{"id":57061373,"uuid":"12192314","full_name":"sumpygump/holograph","owner":"sumpygump","description":"A markdown based documentation system for CSS files written in PHP","archived":false,"fork":false,"pushed_at":"2021-09-06T23:47:30.000Z","size":76,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T11:38:26.951Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sumpygump.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-18T08:09:58.000Z","updated_at":"2021-09-06T23:47:33.000Z","dependencies_parsed_at":"2022-08-24T14:53:44.143Z","dependency_job_id":null,"html_url":"https://github.com/sumpygump/holograph","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumpygump%2Fholograph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumpygump%2Fholograph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumpygump%2Fholograph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumpygump%2Fholograph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sumpygump","download_url":"https://codeload.github.com/sumpygump/holograph/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248220318,"owners_count":21067281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-04T14:17:45.036Z","updated_at":"2025-04-10T12:51:59.520Z","avatar_url":"https://github.com/sumpygump.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Holograph\n=========\n\nHolograph is a tool for managing the CSS documentation of a project, with\nspecific features that enable one to create and maintain a decent CSS style\nguide. It is written in PHP and is similar to [hologram](https://github.com/trulia/hologram)\nand [Knyle Style Sheets](http://warpspire.com/posts/kss/).\n\n## Features\n\n - Composable. Just drop in a require to your composer.json file and start\n   running holograph.\n - Use as a build tool to generate a style guide as well as minify and\n   combine CSS files.\n\n## Installation\n\n### Using Composer\n\nAdd the following to your `composer.json` file:\n\n```json\n{\n    \"require\": {\n        \"sumpygump/holograph\": \"dev-master\"\n    }\n}\n```\n\nThen run composer install to fetch.\n\n    $ composer.phar install\n\nIf you don't have composer already installed, this is my recommendation for\ninstalling it. See\n[getcomposer.org installation instructions](http://getcomposer.org/doc/00-intro.md#globally).\n\n```\n$ curl -sS https://getcomposer.org/installer | php\n$ sudo mv composer.phar /usr/local/bin/composer\n```\n\nOnce installed, there is a CLI command in `vendor/bin/holograph`. The easiest\nway to use holograph is to ensure that `./vendor/bin` is added to your system's\n`$PATH`.\n\n    $ export PATH=$PATH:./vendor/bin\n\n#### Global Installation using Composer\n\nAn alternate way to install holograph so it is available on any project is by\ninstalling it in your `~/.composer` directory using the following command:\n\n    composer global require 'sumpygump/holograph=dev-master'\n\nYou must have `~/.composer/vendor/bin` in your environment PATH.\n\n    $ export PATH=$PATH:~/.composer/vendor/bin\n\n## Usage\n\nThe basic feature of holograph is to generate a style guide based on comments\nadded in your CSS files. Additional Markdown files can also be added to create\nthe styleguide's documentation.\n\n## CSS Files\n\nThe first step in getting use out of Holograph is to format comments blocks in\nyour CSS stylesheets. Add document blocks in your CSS files with some YAML\nand some markdown as documented below.\n\n```css\n    /*doc\n    ---\n    name: badgeSkins\n    ---\n\n    Badges are a way to display a small amount of text or an image within a\n    nicely formatted box.\n\n    Class          | Description\n    -------------- | -----------------\n    badgeStandard  | This is a basic badge\n    badgePrimary   | This is a badge with the trulia orange used on CTAs\n    badgeSecondary | This is a badge with the alternate CTA color (Trulia green)\n    badgeTertiary  | This is a badge for a warning or something negative\n\n\n    ```html_example\n    \u003cstrong class=\"badgeStandard\"\u003eSold\u003c/strong\u003e\n    \u003cstrong class=\"badgePrimary\"\u003eFor Sale\u003c/strong\u003e\n    \u003cstrong class=\"badgeSecondary\"\u003eFor Rent\u003c/strong\u003e\n    ```\n    */\n\n    .badgeStandard {\n      background-color: #999999;\n    }\n\n    .badgePrimary {\n      background-color: #ff5c00;\n    }\n\n    .badgeSecondary {\n      background-color: #5eab1f;\n    }\n```\n\n### Document Blocks\n\nAny comment block starting with `/*doc` will be considered a document block,\nand will be inspected and parsed by the styleguide generator.\n\n```css\n/*doc\nThis is my document block.\n*/\n```\n\n### YAML Matter\n\nA document block must have a YAML block at the top of the comment surrounded by\nlines with three dashes (`---`). YAML is a convenient way to store key-value\npairs. The YAML block must contain at a minimum the `name` key.\n\n```css\n/*doc\n---\nname: media-object\n---\n*/\n```\n\nYAML block key-value pairs consist of a key name on the left followed by a\ncolon, a space, and then the value. For example: `name: button`\n\nThe following document block YAML keys are used by Holograph:\n\nKey      | Meaning\n-------- | ----------------------------------\ntitle    | The title for this component\nname     | A unique name for this component (required)\ncategory | Which category this component appears, in the main navigation\nparent   | The name of the parent's component, to define this component as a child\n\nFull example:\n\n```css\n/*doc\n---\ntitle: Badge Colors\nparent: badge\nname: badgeSkins\ncategory: Components\n---\n*/\n```\n\nThe `title` of the component is used when displaying the heading for that\ncomponent's documentation.\n\nAll components of a given `category` will be put into an HTML file with the\nsame name as the category. Using the default layout template (see below), each\ncategory HTML file will be accessible in the main navigation of the outputed\nstyleguide. Note: If no category is provided, holograph will default the\ncategory to `index` and thus the component documenation will be placed into\n`index.html` of the rendered styleguide.\n\nIf a component is a `parent` (has child components), it will be displayed first,\nfollowed by its child components on the rendered category page.\n\nExample of parent/child definition:\n\n```css\n/*doc\n---\nname: badge\n---\n*/\n\n/*doc\n---\nname: badgeSkins\nparent: badge\n---\n*/\n```\n\nThe above example defines a component named \"badge\" and a child component named\n\"badgeSkins.\" The badgeSkins documentation will be placed below the badge\ndocumentation.\n\n### HTML code examples\n\nIf your markdown documentation in your document blocks contains an fenced code\nblock with the type `html_example`, Holograph will output the sample HTML and\nthe HTML code in the styleguide. This provides a great way to document and\nshowcase example usage of your CSS classes.\n\nExample:\n\n    ```html_example\n    \u003cdiv class=\"page\"\u003e\n        \u003cbutton class=\"btn\"\u003eClick\u003c/button\u003e\n    \u003c/div\u003e\n    ```\n\n## Markdown Files\n\nYou can also place Markdown files in the source directory. These files will be\nprocessed and included in the destination directory.\n\nMarkdown files (*.md) will be renamed to *.html. For example `overview.md` will\nbe renamed to `overview.html` when included in the destination directory. Each\nmarkdown file will also be added to the main navigation rendered to the styleguide.\n\nNote: Holograph includes the [extra-extended](https://github.com/egil/php-markdown-extra-extended)\nflavor of Markdown syntax, which suppors markdown syntax such as fenced code blocks\nand tables.\n\n## Configuration\n\nHolograph uses a configuration file to define paths and other aspecst for the\ncurrent directory's build parameters.\n\nThe default name for the configuration file is `holograph.yml`. Holograph looks\nfor a file of this name in the current directory when building.\n\nThe following is the default config file.\n\n```yml\n# Holograph configuration\n\n# The title for this styleguide {{title}}\ntitle: 'Style Guide'\n\n# The directory containing the source files to parse\nsource: ./components\n\n# The directory to generate files to\ndestination: ./docs\n\n# Directory location of assets needed to accompany the docs (layout.html)\ndocumentation_assets: ./templates\n\n# Boolean indicating whether to use hologram compatibility\n# When true it will expect header.html and footer.html instead of layout.html\ncompat_mode: false\n\n# Any other asset folders that need to be copied to the destination folder\ndependencies:\n    - ./build\n\n# Build option to actually compiles CSS files (options: none, minify)\npreprocessor: minify\n\n# Directory to build the final CSS files\nbuild: ./build/css\n\n# The main stylesheet to be included {{main_stylesheet}}\nmain_stylesheet: build/css/screen.css\n```\n\n### File paths\n\nHere is an explanation of the file paths in the config file.\n\nPath                 | Explanation\n---------------------|---------------------\nsource               | The source path is a directory where the subject CSS and Markdown files reside\ndestination          | The destination path is where the styleguide will be written\ndocumentation_assets | This is a path where the template files and styles for the styleguide itself are kept\ndependencies         | Dependencies is an array of multiple paths, the contents of which should also\n                     | be copied to the destination directory. Example: fonts, images used by the examples.\nbuild                | The build path is where the preprocessor will write its output file(s).\n\n### Documentation Assets\n\nThe documentation assets provides template files and CSS files used to render\nthe structure of the styleguide. By default, Holograph looks for a file called\n`layout.html` in the documenation_assets directory. If none is found it will\nuse the default layout file in the `default-templates` directory in the Holograph\ninstall directory.\n\nThe `layout.html` file can contain the following tokens that will be replaced\nduring the build step:\n\n - `{{title}}` - This will be replaced with the title defined in the config file\n - `{{main_stylesheet}}` - This will be replaced with the path to the stylesheet\n                           generated by the preprocessor and represents the styles\n                           you are wishing to document with the styleguide.\n - `{{navigation}}` - This will be replaced with a `\u003cul\u003e` of the generated HTML files (categories)\n - `{{content}}` - This will be replaced with the content of the styleguide documentation.\n\nYou are encouraged to create a style guide layout file that will fit with your site's\nbranding or design. Any subfolders in the `documentation_assets` will also be copied\ninto the destination folder so you can include assets like fonts, images, css and\njavascript to be used by the styleguide layout.\n\n## Running holograph\n\nHolograph can be run from the command line\n\n    $ holograph\n    Holograph 0.7\n    A markdown based build and documentation system for OOCSS\n\n    Usage: holograph \u003caction\u003e [OPTIONS]\n\n    Actions:\n      init : Initialize environment for holograph (write conf file with defaults)\n      config : Show current configuration parameters\n      build : Build the style guide HTML/CSS\n      help : Display program help and exit\n\n    Options:\n      -c \u003cfile\u003e | --conf \u003cfile\u003e : Use alternate configuration file\n      -h | --help : Display program help and exit\n      -q | --quiet : Quiet mode (Don't output anything)\n      -v | --verbose : Verbose output mode\n      --version : Display program version and exit\n      --compat : Use hologram compatible mode (header.html/footer.html)\n\n### init\n\nAn easy way to create a clean `holograph.yml` config file in the current\ndirectory is to run the `holograph init` command.\n\n### config\n\nRunning `holograph config` will display the current configuration parameters in\nthe config file of the current directory.\n\n### build\n\nTo build the styleguide from the source *.css and *.md files, run `holograph\nbuild`. This will complete the following tasks:\n\n1. read the config file\n1. run the preprocessor (optimization step)\n1. parse the CSS and Markdown files\n1. generate the styleguide HTML files\n1. copy the documentation assets and any other defined dependencies into the\n   destination directory.\n\n## The Preprocessor\n\nThe preprocessor is a mechanism to run a optimization step prior to building the\nstyleguide documentation. The current version only supports the options `minify`\nor `none`. The \"minify\" option will use [Minify](https://github.com/mrclay/minify)\nto minify the CSS files within the source directory and then combine them into one\nfile. This is currently a limited operation. It is expected that this functionality\nwill be expanded to support more complex configurations and other optimization\nengines such as Sass or Less.\n\nThe following settings in the config file are used by the preprocessor:\n\n    preprocessor: minify\n\nThe \"preprocessor\" key provides a directive of which minify option to use. Currently\nthe options are \"minify\" or \"none\".\n\n    build: ./build/css\n\nThe \"build\" key defines a directory where the final optimized CSS file should be\nwritten.\n\n    main_stylesheet: build/css/screen.css\n\nThe \"main_stylesheet\" is the file path and name the preprocessor uses as the\nfinal output file for the optimized stylesheet. This value is also used to\ninclude the destination stylesheet in the styleguide build output.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumpygump%2Fholograph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsumpygump%2Fholograph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumpygump%2Fholograph/lists"}