PHPackages                             cspray/blogisthenics - 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. cspray/blogisthenics

ActiveLibrary[Utility & Helpers](/categories/utility)

cspray/blogisthenics
====================

Put your blog generation on a diet with Blogisthenics!

v0.4.0(1y ago)069[4 issues](https://github.com/cspray/blogisthenics/issues)PHPPHP ^8.1CI passing

Since Jul 24Pushed 1y ago1 watchersCompare

[ Source](https://github.com/cspray/blogisthenics)[ Packagist](https://packagist.org/packages/cspray/blogisthenics)[ RSS](/packages/cspray-blogisthenics/feed)WikiDiscussions main Synced today

READMEChangelog (5)Dependencies (11)Versions (11)Used By (0)

Blogisthenics
=============

[](#blogisthenics)

Are you looking for a static site generator with the following features:

- A [SPA](https://en.wikipedia.org/wiki/Single-page_application) using the latest JavaScript Web Components?
- The newest CSS frameworks baked right in?
- Access to the fanciest, most modern templating engine?
- Integration with your favorite framework?

Then this project isn't for you because Blogisthenics doesn't offer any of those things! And never will! What do we give you instead?

- A way to create a boring ol' multi-page application using HTML, Markdown, and a minimal amount of CSS; where clicking on a link makes the whole page refresh. So old school!
- Powerful, no-frills templating engine that's been in use for over 20 years. PHP itself!
- Customize your dynamic content with Front Matter... not written in YAML!
- Absolutely no JavaScript or related tooling out-of-the-box. I prefer to have just 1 shitty language in my site generators, thank-you-very-much!
- Cohesive, type-safe, testable mechanisms for programmatically controlling the content of your site!

Usage Guide
-----------

[](#usage-guide)

Oh, shit. You're still here? In all honesty, you probably shouldn't use this software! There's just an ass-load of site generators out there and nearly all of them are going to be more supported than whatever this ball of crap turns into. The stuff I write below is mostly for my own benefit so when I come back here in 6 months I can figure out what the hell is going on.

### Directory Structure

[](#directory-structure)

Blogisthenics follows a principle that there are reasonable defaults for your site configuration, but you can override any of the defaults to customize your installation. Your directory structure should resemble the following:

```
/.blogisthenics
    config.json                 # Configure Blogisthenics, if not provided default config will be used
/content                        # The actual content for your site goes here
    /assets                     # CSS, JS, images ... isn't treated specially, convention to put stuff here
    /blog                       # Your blog articles ... could be named whatever you want
    index.md                    # Markdown files are ok. Front-matter parsing and layouts are supported
    about.html                  # HTML files are ok too, you won't get any parsing or layout support though
    contact.html.php            # Add a PHP extension to enable front-matter parsing and layout support
/data
    ...                         # Store JSON files here to access in the KeyValueStore
/layouts
    main.html.php               # Store PHP template files here to use as layouts
    article.html.php            # Layouts can be nested as deep as you want, but probably a logical limit
    foo.md.php                  # Support Markdown templates
/src
    /ContentGeneratedHandler
        ...                     # Any ContentGeneratedHandler instances
    /ContentWrittenHandler
        ...                     # Any ContentWrittenHandler instances
    /DataProvider
        ...                     # Any DataProvider instances
    /DynamicContentProvider
        ...                     # Any DynamicContentProvider instances
    /Formatter
        ...                     # Any Formatter instances
    /TemplateHelperProvider
        ...                     # Any TemplateHelperProvider instances

```

### Content Overview

[](#content-overview)

Content for your site gets lumped into three categories:

- Static Assets
- Layouts
- Pages

#### Static Assets

[](#static-assets)

Static assets are any content in your site that should not be dynamically rendered, whatever is in the file gets copied over exactly, with the same path, when the site is built. Specifically the following functionalities are **not** supported by static assets.

- Front Matter Parsing
- Template processing, i.e. no variables
- Multiple extension formatting support

#### Pages

[](#pages)

Pages are `.html`, `.md`, and `.php` files that act as specific content for a path that will be added to your site. Pages are expected to be only partial HTML documents and must define a layout. If a layout is not explicitly defined in the Front Matter of a page we use the default layout from the site configuration.

#### Layouts

[](#layouts)

Layouts are `.md` and `.php` files that act as the outer chrome for pages. Layouts can be inserted into other layouts. The below example demonstrates a minimal layout, typically named something like `main.html.php` or `default.html.php`.

```
>

        title ?? 'Blogisthenics' ?>

        yield() ?>

```

Note the call to `$this->yield()`, when in a layout this is required to output the content being injected. If you attempt to call `$this->yield()` from a non-layout piece of Content an exception will be thrown. Check out the "Templating" section below for more details on using Pages and Layouts.

### Templating

[](#templating)

Blogisthenics uses PHP itself as the templating engine. On top of that we add some functionality to allow the following features:

- Nesting an arbitrary level of layouts
- Auto-escaping all values, including ability to escape contextually.
- Providing access to the FrontMatter of the layout and page
- Provide read-only access to the loaded data
- Allow the creation of helper methods for outputting common pieces of content

The majority of the functionality described in this section refers to the `Cspray\Blogisthenics\Context` object. This object is defined as `$this` in your templates. The simplest templates might look something like the following.:

```

>

        title ?? 'Blogisthenics README' ?>

        yield() ?>

```

```

{
    "title": "Home Page"
}

#

Yep, that's right. The Front Matter is just a JSON object. Slap a new line on the end of
that bad boy, then start writing your content. The values available in the page are the
values found in your Front Matter.
```

When built, your site would include an `index.html` file that resembles the following:

```
>

        Home Page

        "Home Page"

            Yep, that's right. The Front Matter is just a JSON object. Slap a new line on the end of that bad boy, then start writing your content. The values available in the page are the values found in your Front Matter.

```

#### Template Helpers

[](#template-helpers)

Sometimes what you want to do might be too advanced for a static front matter or would be easier to share across many pages and layouts if it was encapsulated in a method you could invoke inside a template. Using the `TemplateHelperProvider` you can add template helper methods easily and then get access to them in your templates.

To utilize template helpers you'll have to implement some PHP code. In addition to whatever your helper does you'll have to make sure it gets integrated with Blogisthenics. Fortunately, that's easy to do thanks to [Annotated Container](https://github.com/cspray/annotated-container). This code should live somewhere in the `src` directory of your Blogisthenics site.

```