Sculpin

https://sculpin.io/documentation
Admin
Sculpin is a PHP-based static site generator that converts Markdown files and Twig templates into...
Tokens:13,335
Snippets:140
Trust Score:9.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run Sculpin server for Tailwind Blog

Source: https://sculpin.io/documentation/additional-skeletons

Start Sculpin's built-in server with watch mode to preview the site.

```bash
vendor/bin/sculpin generate --watch --server

```

--------------------------------

### Source subdirectories example

Source: https://sculpin.io/documentation/sources

Illustrates dividing content into subdirectories within source/, such as a 'stories' folder.

```text
|-- source/
|  |-- stories/
|     |-- the-fox-and-the-greyhound.md
|     |-- scalar-morghulis.md
|  |-- about.md
|  |-- contact.md

```

--------------------------------

### Example project entry in source/_projects/sculpin.md

Source: https://sculpin.io/documentation/content-types/custom-types

A sample Markdown file for a new project entry. It uses the 'project' layout, sets a title, and includes tags for taxonomy.

```markdown
---
layout: project
title: Project SCULPIN
tags: [blog, howto]
---
Lorem ipsum dolor belta lowdah ...

```

--------------------------------

### Build assets for Tailwind Blog

Source: https://sculpin.io/documentation/additional-skeletons

Run Yarn Encore to build the project's assets after installation.

```bash
yarn encore dev

```

--------------------------------

### Configure a custom content type 'projects' with all options

Source: https://sculpin.io/documentation/content-types/custom-types

Shows the expanded default configuration for the 'projects' content type. All options are optional; this example lists every configurable setting, including the source path, singular name, layout, enabled flag, and taxonomies.

```yaml
sculpin_content_types:
    projects:
        type: path
        path: _projects
        singular_name: project
        layout: project
        enabled: true
        taxonomies:
            - tags

```

--------------------------------

### Example theme directory structure

Source: https://sculpin.io/documentation/themes

Shows the directory structure for a Sculpin project with a theme and a parent theme. It includes the app config, source files, and theme directories.

```text
app/
  config/
    sculpin_kernel.yml
source/
  index.html.twig
  css/
    page.css
  themes/
    myApp/
      parentTheme/
        _layouts/
          default.html.twig
        images/
          logo.png
      myTheme/
        _layouts/
          default.html.twig
        css/
          style.css
          page.css

```

--------------------------------

### Enable SculpinRedirectBundle

Source: https://sculpin.io/documentation/extending-sculpin/configuration

Example of enabling the mavimo/sculpin-redirect-bundle by adding its class name to the array returned from getAdditionalSculpinBundles. Must return the class name as a string, not an instance or hashmap.

```php
<?php

use Mavimo\Sculpin\Bundle\RedirectBundle\SculpinRedirectBundle;
use Sculpin\Bundle\SculpinBundle\HttpKernel\AbstractKernel;

class SculpinKernel extends AbstractKernel
{
    protected function getAdditionalSculpinBundles(): array
    {
        return [
            SculpinRedirectBundle::class,
        ];
    }
}

```

--------------------------------

### Wrap content in content_wrapper block in _views/project.html

Source: https://sculpin.io/documentation/layouts

Example _views/project.html layout that wraps content in a content_wrapper block. Use this pattern for multiple levels of view inheritance so content gets embedded in the project view, then in the default view.

```twig
{% extends 'default' %}

{% block content_wrapper %}
<article>
  <header>
    <h2>{{ page.title }}</h2>
  </header>
  <section class="main_body">
    {{ page.blocks.content }}
  </section>
</article>
{% endblock %}

```

--------------------------------

### Override site.url with --url option

Source: https://sculpin.io/documentation/basic-project

Overrides the `site.url` configuration to generate URLs matching the installation path, e.g., for a subdirectory.

```bash
vendor/bin/sculpin generate --url=http://my.dev.host/blog-skeleton/output_dev
```

--------------------------------

### Import sculpin_site.yml into environment-specific config

Source: https://sculpin.io/documentation/configuration

Environment-specific meta data overrides generic meta data. This example imports the global sculpin_site.yml and sets a production Google Analytics tracking ID.

```yaml
imports:
    - sculpin_site.yml
google_analytics_tracking_id: UA-PRODUCTION-372

```

--------------------------------

### Frontmatter with title variable

Source: https://sculpin.io/documentation/sources

Example of a markdown file with a title in YAML frontmatter; the title is not rendered unless the view template explicitly requests it.

```markdown
---
title: Hello World
---

This is the content of my page.

```

--------------------------------

### Override posts permalink strategy

Source: https://sculpin.io/documentation/content-types/posts

Override the default permalink strategy for posts by modifying app/config/sculpin_kernel.yml. This example sets the permalink to include the blog prefix and year, month, day, and filename.

```yaml
sculpin_content_types:
    posts:
        permalink: blog/:year/:month/:day/:filename/

```

--------------------------------

### Process markdown with markdown filter in Twig

Source: https://sculpin.io/documentation/extending-sculpin/community-extensions

Process a markdown string from within Twig using the markdown filter. The example passes the variable some_content through the filter.

```twig
{{ some_content|markdown }}
```

--------------------------------

### Use theme layout and theme_path() in Twig template

Source: https://sculpin.io/documentation/themes

Example Twig template that uses the theme layout and theme_path() helper to reference theme assets. It demonstrates overriding the default layout and using assets from the theme and parent theme.

```twig
---
layout: default
---
{# 
  This view will use the layout from 
  source/themes/myApp/myTheme/_layouts/default.html.twig,
  which overrides the default layout in parentTheme.
#}

{% block stylesheets %}
  {# 
    This will use a stylesheet from 
    source/themes/myApp/myTheme/css/style.css 
  #}
  <link rel="stylesheet" href="{{ theme_path("css/style.css") }}" />

  {#
    This will use a stylesheet from source/css/page.css,
    which overrides the page.css in childTheme
  #}
  <link rel="stylesheet" href="{{ theme_path("css/page.css") }}" />
{% endblock}

{% block logo %}
  {#
    This will use an image from 
    source/themes/myApp/parentTheme/images/logo.png 
  #}
  <img src="{{ theme_path("images/logo.png") }}" />
{% endblock}

```

--------------------------------

### Generate thumbnail with thumbnail() in Twig

Source: https://sculpin.io/documentation/extending-sculpin/community-extensions

Use the thumbnail() Twig function to generate a thumbnail of an image with specified width and height. The example shows an anchor wrapping an image tag that uses the function.

```html
<a href="image.jpg"><img src="{{ thumbnail('image.jpg', 100, 100) }}"></a>
```

--------------------------------

### Sort array by key with sortbyfield in Twig

Source: https://sculpin.io/documentation/extending-sculpin/community-extensions

Sort an array by a specified key using the sortbyfield filter. The example iterates over myArray sorted by the 'array_sort_key' field and outputs that field for each item.

```twig
{% for i in myArray | sortbyfield('array_sort_key') %}
  {{ i.array_sort_key }}
{% endfor %}
```

--------------------------------

### Generate production build with --env=prod

Source: https://sculpin.io/documentation/basic-project

Builds the site for production, outputting to `output_prod`.

```bash
vendor/bin/sculpin generate --env=prod
```

--------------------------------

### Sample projects index page template

Source: https://sculpin.io/documentation/content-types/custom-types

Template for listing all projects. Uses the 'projects' data provider via the 'use' front matter and iterates over 'data.projects' to output links.

```html
---
use: [projects]
---
<ul>
    {% for project in data.projects %}
        <li><a href="{{ project.url }}">{{ project.title }}</a></li>
    {% endfor %}
</ul>

```

--------------------------------

### Generate with --watch and --server for local development

Source: https://sculpin.io/documentation/basic-project

Combines `--watch` and `--server` to monitor source changes and serve the site at localhost:8000 in dev mode.

```bash
vendor/bin/sculpin generate --watch --server
```

--------------------------------

### Run sculpin content:create with boilerplate and tags

Source: https://sculpin.io/documentation/content-types/custom-types

Creates a new 'projects' content type with boilerplate files and a 'tags' taxonomy. The `-b` option generates boilerplate files, and `-t tags` adds the taxonomy.

```bash
vendor/bin/sculpin content:create -b -t tags projects

```

--------------------------------

### Generate static site with vendor/bin/sculpin generate

Source: https://sculpin.io/documentation/basic-project

Runs the `generate` command to compile source files into static HTML in `output_dev`.

```bash
vendor/bin/sculpin generate
```

--------------------------------

### Serve pre-generated files with vendor/bin/sculpin serve

Source: https://sculpin.io/documentation/basic-project

Serves already generated files without automatic regeneration.

```bash
vendor/bin/sculpin serve
```

--------------------------------

### Basic source directory structure

Source: https://sculpin.io/documentation/sources

Shows the default source/ directory that Sculpin expects in the project root.

```text
|-- source/

```

--------------------------------

### Create Tailwind Blog project

Source: https://sculpin.io/documentation/additional-skeletons

Use Composer to create a new Sculpin project from the Tailwind Blog skeleton. Replace 'myblog' with your desired directory name.

```bash
composer create-project beryllium/sculpin-tailwind-blog-skeleton myblog

```

--------------------------------

### Create Tailwind Product Site project

Source: https://sculpin.io/documentation/additional-skeletons

Use Composer to create a new Sculpin project from the Tailwind Product Site skeleton. Replace 'myproduct' with your desired directory name.

```bash
composer create-project beryllium/sculpin-tailwind-landing-skeleton myproduct

```

--------------------------------

### Site meta data file structure

Source: https://sculpin.io/documentation/configuration

Shows the optional configuration files for site meta data. The sculpin_site.yml file holds global defaults, while sculpin_site_${env}.yml holds environment-specific overrides.

```text
|-- app/
|  `-- config/
|     |-- sculpin_site.yml         # Site meta data (optional)
|     `-- sculpin_site_${env}.yml  # Environment specific meta data (optional)

```

--------------------------------

### Generate site for production environment with --env=prod

Source: https://sculpin.io/documentation/configuration

Use this command to generate your site for the production environment. The --env=prod option overrides the default dev environment.

```bash
vendor/bin/sculpin generate --watch --server --env=prod

```

--------------------------------

### Sample project tags projects index page template

Source: https://sculpin.io/documentation/content-types/custom-types

Template that leverages the tag index generator to create a page for every tag and list its projects. Uses the 'projects_tag_index' generator and iterates over 'page.tag_projects'.

```html
---
generator: projects_tag_index
---
<h1></h1>
<ul>
    {% for project in page.tag_projects %}
        <li><a href="{{ project.url }}">{{ project.title }}</a></li>
    {% endfor %}
</ul>

```

--------------------------------

### Production environment output structure

Source: https://sculpin.io/documentation/sources

Directory structure after running `sculpin generate --env=prod`, producing output_prod/index.html; upload output_prod to the server.

```text
|-- source/
   `-- index.md
|-- output_dev/
   `-- index.html
|-- output_prod/
   `-- index.html

```

--------------------------------

### Generate with custom port using --port option

Source: https://sculpin.io/documentation/basic-project

Uses the `--port` option to run the built-in web server on a different port.

```bash
vendor/bin/sculpin generate --watch --server --port=8888
```

--------------------------------

### Sample project tags index page template

Source: https://sculpin.io/documentation/content-types/custom-types

Template for listing all tags used to tag projects. Uses the 'projects_tags' data provider and iterates over 'data.projects_tags' to output tag links.

```html
---
use: [projects_tags]
---
<ul>
    {% for tag,projects in data.projects_tags %}
        <li><a href="{{ site.url }}/projects/tags/{{ tag|url_encode(true) }}">{{ tag }}</a></li>
    {% endfor %}
</ul>

```

--------------------------------

### Dev environment output structure

Source: https://sculpin.io/documentation/sources

Directory structure after running `sculpin generate --watch --server`, producing output_dev/index.html.

```text
|-- source/
   `-- index.md
|-- output_dev/
   `-- index.html

```

--------------------------------

### Single source file structure

Source: https://sculpin.io/documentation/sources

Shows a source directory containing only index.md before generation.

```text
|-- source/
   `-- index.md

```

--------------------------------

### Output of sculpin content:create command

Source: https://sculpin.io/documentation/content-types/custom-types

Shows the YAML configuration to add to `app/config/sculpin_kernel.yml` and the boilerplate generation message. The YAML defines the content type with path, singular name, layout, permalink, and taxonomies.

```text
Generating new content type: projects
=============================================
YAML to add to app/config/sculpin_kernel.yml:
=============================================

sculpin_content_types:
    projects:
        type: path
        path: _projects
        singular_name: project
        layout: project
        enabled: true
        permalink: projects/:title
        taxonomies:
            - tags

=================END OF YAML=================


Generating boilerplate for portfolio

```

--------------------------------

### Boilerplate file structure generated by -b option

Source: https://sculpin.io/documentation/content-types/custom-types

Lists the directories and files created by the `-b`/`--boilerplate` option. These are placeholder files for the content type, layout, taxonomy listing, and main list.

```text
`-- source/
   |-- _projects/          - Folder that stores Projects
   |-- _views/
   |   `-- project.html    - Layout file for Projects
   |-- projects/
   |   |-- tags/
   |   |   `-- tag.html    - Listing template for individual "tags"
   |   `-- tags.html       - Main list for "tags" taxonomy
   `-- projects.html       - Template for the list of projects

```

--------------------------------

### Sculpin project file structure

Source: https://sculpin.io/documentation/basic-project

Default file structure for a Sculpin project. The `source/` directory contains content and templates, `app/` holds configuration, and `output_${env}/` holds generated files.

```text
|-- app/
|  |-- SculpinKernel.php           # Custom Sculpin kernel
|  `-- config/
|     |-- sculpin_kernel.yml       # Sculpin's configuration
|     |-- sculpin_site.yml         # Site meta data
|     `-- sculpin_site_${env}.yml  # Env specific meta data
|-- output_${env}/                 # Env specific generated files
|-- source/                        # Files in here are read and compiled
|  |-- _posts/                     # Individual blog posts live here
|  `-- _views/                     # Templates
`-- composer.json                  # Dependencies
```

--------------------------------

### Sculpin source file and internal content wrapper

Source: https://sculpin.io/documentation/layouts

Shows how Sculpin wraps a source file with YAML frontmatter in a block named content. The first block is the original source; the second is how Sculpin internally treats it.

```markdown
---
layout: default
---

# This is a markdown file with YAML frontmatter

```

```twig
{% extends "default" %}
{% block content %}

# This is a markdown file with YAML frontmatter
{% endblock %}

```

--------------------------------

### Sculpin Kernel Configuration File Structure

Source: https://sculpin.io/documentation/configuration

Shows the optional location of the sculpin_kernel.yml file within the app/config directory.

```text
|-- app/
|  `-- config/
|     `-- sculpin_kernel.yml       # Sculpin's configuration (optional)

```

--------------------------------

### Pass source data to layout and render output

Source: https://sculpin.io/documentation/layouts

Demonstrates passing data from a source file to its layout. The source defines special_value; the default template checks it and renders it; the final output shows the rendered result.

```markdown
---
layout: default
special_value: nice
---

# This is a markdown file with YAML frontmatter

```

```twig
<html>
{% if page.special_value is defined %}
    Special value exists and is <strong>{{ page.special_value }}</strong>!.
{% endif %}
{% block content %}Fallback content{% endblock %} 
</html>

```

```html
<html>
    Special value exists and is <strong>nice</strong>!.
<h1>This is a markdown file with YAML frontmatter</h1>
</html>

```

--------------------------------

### Define a custom content type 'projects'

Source: https://sculpin.io/documentation/content-types/custom-types

Defines a custom content type named 'projects' with default settings. This minimal configuration enables the content type and wires up default behavior.

```yaml
sculpin_content_types:
    projects:

```

--------------------------------

### Custom Permalink Configuration with Date Tags

Source: https://sculpin.io/documentation/configuration

Defines a custom permalink pattern using :year, :month, :day, and :slug_title tags.

```yaml
sculpin:
    permalink: blog/:year/:month/:day/:slug_title

```

--------------------------------

### Register theme in sculpin_kernel.yml

Source: https://sculpin.io/documentation/themes

Registers the theme name in the Sculpin kernel configuration. The theme is then looked up in source/themes/myApp/myTheme.

```yaml
# app/config/sculpin_kernel.yml
sculpin_theme:
  theme: myApp/myTheme

```

--------------------------------

### Custom Permalink with Trailing Slash

Source: https://sculpin.io/documentation/configuration

Adds a trailing slash to generated permalinks, resulting in files like blog/your-title/index.html and links like blog/your-title/.

```yaml
sculpin:
    permalink: blog/:title/

```

--------------------------------

### Paginate custom content type 'projects'

Source: https://sculpin.io/documentation/content-types/custom-types

Template for paginating custom types. Uses the 'pagination' generator with provider 'data.projects' and loads all projects into 'data.projects' via the 'use' list.

```html
---
generator: pagination
pagination:
  provider: data.projects
use:
  - projects
---
<h1>Paginated Projects</h1>

```

--------------------------------

### Configure Default Permalink in sculpin_kernel.yml

Source: https://sculpin.io/documentation/configuration

Sets the default permalink style to 'pretty' for all sources via the Sculpin bundle configuration.

```yaml
sculpin:
    permalink: pretty

```

--------------------------------

### Custom Permalink Using :folder Tag

Source: https://sculpin.io/documentation/configuration

Uses the :folder tag to include the folder structure in the permalink, e.g., blog/:folder:basename.html.

```yaml
sculpin:
    permalink: blog/:folder:basename.html

```

--------------------------------

### SculpinKernel template

Source: https://sculpin.io/documentation/extending-sculpin/configuration

Template for creating a custom Sculpin kernel in app/SculpinKernel.php. Override getAdditionalSculpinBundles to return an empty array initially.

```php
<?php

class SculpinKernel extends \Sculpin\Bundle\SculpinBundle\HttpKernel\AbstractKernel
{
    protected function getAdditionalSculpinBundles(): array
    {
        return [
        ];
    }
}

```

--------------------------------

### Pagination generator usage with max_per_page and posts provider

Source: https://sculpin.io/documentation/generators

Configure a source to use the pagination generator with a maximum of 3 items per page, pulling items from the 'posts' collection. The template loops over page.pagination.items to list items and uses page.pagination.previous_page and page.pagination.next_page to render navigation links. The navigation block is wrapped in a conditional that checks for the existence of either previous or next page.

```markdown
---
generator: pagination
pagination:
    max_per_page: 3
use:
    - posts
---
<ul>
    {% for item in page.pagination.items %}
        <li><a href="{{ item.url }}">{{ item.title }}</a></li>
    {% endfor %}
</ul>

<nav>
{% if page.pagination.previous_page or page.pagination.next_page %}
    {% if page.pagination.previous_page %}
        <a href="{{ site.url }}{{ page.pagination.previous_page.url }}">Newer Items</a>
    {% endif %}
    {% if page.pagination.next_page %}
        <a href="{{ site.url }}{{ page.pagination.next_page.url }}">Older Items</a>
    {% endif %}
{% endif %}
</nav>
```

--------------------------------

### Change Theme in sculpin_kernel.yml

Source: https://sculpin.io/documentation/configuration

Sets the theme to 'acme/awesome-theme' via the sculpin_theme bundle configuration.

```yaml
sculpin_theme:
    theme: acme/awesome-theme

```

--------------------------------

### Nested YAML frontmatter structure

Source: https://sculpin.io/documentation/sources

Shows how to define nested YAML frontmatter and reference it with dot notation, e.g., {{ page.something.here.also }}.

```markdown
---
layout: default
something:
    here:
        very: deep
        also: deep
---

We can reference `{{ page.something.here.also }} === deep`.

```

--------------------------------

### Markdown file with YAML frontmatter

Source: https://sculpin.io/documentation/sources

A markdown file with YAML frontmatter delimited by ---, enabling Twig formatting and access to frontmatter variables via page.KEY.

```markdown
---
layout: default
---

# This is a markdown file with YAML frontmatter

```

--------------------------------

### Watch assets for Tailwind Blog

Source: https://sculpin.io/documentation/additional-skeletons

Run Yarn Encore in watch mode to automatically regenerate assets when editing CSS, JS, or images. Run in a separate terminal.

```bash
yarn encore dev --watch

```

--------------------------------

### Default posts content type configuration

Source: https://sculpin.io/documentation/content-types/posts

Default configuration for the posts content type in Sculpin. It sets the type to path, the source directory to _posts, the permalink strategy to pretty, and enables tags and categories taxonomies.

```yaml
sculpin_content_types:
    posts:
        type: path
        path: _posts
        permalink: pretty
        taxonomies:
            - tags
            - categories

```

--------------------------------

### Render content block in Twig layout

Source: https://sculpin.io/documentation/layouts

Two equivalent ways to render a Source's content block in a Twig layout. Use either to make a layout work with Sculpin.

```twig
{% block content %}{% endblock %}

```

```twig
{{ page.blocks.content }}

```

--------------------------------

### Define parent theme in theme.yml

Source: https://sculpin.io/documentation/themes

Defines the parent theme for a theme by creating a theme.yml file in the theme directory. The parent theme is used for asset resolution when assets are not found in the child theme.

```yaml
# source/themes/myApp/myTheme/theme.yml
parent: 'myApp/parentTheme'

```

--------------------------------

### Markdown without frontmatter (not SEO-friendly)

Source: https://sculpin.io/documentation/sources

Plain markdown without YAML frontmatter; omits the HTML <title> element, which is not SEO-friendly.

```markdown
# Hello World

This is the content of my page. But it's not very SEO-friendly because it's missing the HTML element <title>.

```

--------------------------------

### Markdown file without YAML frontmatter

Source: https://sculpin.io/documentation/sources

A plain markdown file that lacks YAML frontmatter, so it is not formatted with Twig.

```markdown
# This is a markdown file without YAML frontmatter

```

--------------------------------

### Ignore Files Ending with Tilde in sculpin_kernel.yml

Source: https://sculpin.io/documentation/configuration

Configures Sculpin to ignore all files ending with a tilde (~) using the ignore option.

```yaml
sculpin:
    ignore: ["**/*~"]

```

--------------------------------

### List related posts with page.related in Twig

Source: https://sculpin.io/documentation/extending-sculpin/community-extensions

List five related posts below a post by checking page.related and looping over it. Each item links to the related post's source URL and displays its title.

```twig
{% if page.related %}
<ul>
  {% for relate in page.related %}
  <li><a href="{{ relate.source.url }}">{{ relate.title }}</a></li>
  {% endfor %}
</ul>
{% endif %}
```

--------------------------------

### Disable posts content type

Source: https://sculpin.io/documentation/content-types/posts

Disable the posts content type entirely by setting enabled to false in the sculpin_content_types configuration.

```yaml
sculpin_content_types:
    posts:
        enabled: false

```
Tokens:
Raw