Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

blocksy

/blocksy

Konfiguruje motyw Blocksy w WordPressie: opcje globalne, nagłówek i stopkę, kolory, typografię, menu i bloki treści przez WP-CLI.

Repozytorium
blocksy-skill ↗
Licencja
MIT
Ostatnia zmiana repozytorium
09.11.2026

Ocena i bezpieczeństwo

95/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
2
Adresy URL w SKILL.md
5
Przestarzałość

Brak sygnałów. Repozytorium zmienione 09.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

Co robi i kiedy

Konfiguruje motyw Blocksy w WordPressie: opcje globalne, nagłówek i stopkę, kolory, typografię, menu i bloki treści przez WP-CLI.

Oryginalny opis (EN)

Use when configuring a WordPress site that runs the Blocksy theme, Blocksy Child, Blocksy Companion, or Blocksy Companion Pro — global theme options, header/footer builder, colors, typography, menus, Content Blocks/popups, per-page settings, extensions, custom fonts, and applying settings with WP-CLI (incl. DDEV and LocalWP) or remote REST when there is no server access. Also provides Blocksy design tokens (palette, typography, widths, breakpoints, CSS variables and classes) to other skills that build Gutenberg block pages (GreenLight/GreenShift, core blocks, any block suite) on a Blocksy site

Jak działa

  1. First decision: which adapter?
  2. Non-negotiable rules
  3. Pro gate
  4. Building pages with another skill
  5. The plan format
  6. Workflow
  7. Adapters in one page
  8. What lives where
  9. Data files
  10. Safety
Sekcje z nagłówków SKILL.md, w oryginale · 355 linii, 2 004 słów
Podgląd SKILL.md
---
name: blocksy
description: Use when configuring a WordPress site that runs the Blocksy theme, Blocksy Child, Blocksy Companion, or Blocksy Companion Pro — global theme options, header/footer builder, colors, typography, menus, Content Blocks/popups, per-page settings, extensions, custom fonts, and applying settings with WP-CLI (incl. DDEV and LocalWP) or remote REST when there is no server access. Also provides Blocksy design tokens (palette, typography, widths, breakpoints, CSS variables and classes) to other skills that build Gutenberg block pages (GreenLight/GreenShift, core blocks, any block suite) on a Blocksy site. Triggers on Blocksy, Blocksy Companion, Blocksy Pro, header builder, footer builder, Content Blocks, custom fonts, Blocksy extensions, Blocksy settings import/export, or building/styling pages on a Blocksy site.
license: MIT
---

# Blocksy

Configure a Blocksy site by writing a **plan** and applying it through one of
the adapters. The mechanics are stable; the option IDs come from the installed
Blocksy version.

## First decision: which adapter?

| Situation | Adapter | Coverage |
| --- | --- | --- |
| Shell / SSH / DDEV / LocalWP / WP-CLI available | **WP-CLI** (`scripts/wp-local.sh`, `scripts/inspect.php`, `scripts/apply.php`) | Full |
| No shell, but can install a plugin from wp-admin | **Blocksy Bridge REST** (`dist/blocksy-bridge.zip`, `scripts/remote.mjs`) | Full |
| No plugin install, only wp-admin + REST | **Core REST fallback** | Menus, pages/posts, per-page Blocksy meta only |
| No automation possible | **Manual / assisted** | Generated plan + Customizer import / manual Content Blocks |

**The answer to "no server access" is the bridge plugin.** It is one
self-contained PHP file that exposes a narrow, authenticated REST API for
Blocksy settings. Install it once from wp-admin, then keep working over HTTPS
with a token or WordPress Application Password.

Read `references/adapters.md` before choosing. A site with `.ddev/config.yaml`
in its root or a parent is a DDEV project: read `references/ddev.md`.

## Non-negotiable rules

1. **The active theme owns the settings.** If Blocksy Child is active, theme
   options live in `theme_mods_blocksy-child`, not `theme_mods_blocksy`.
   Always write through `set_theme_mod()` or the bridge, never to a fixed option
   name.
2. **Use WordPress APIs for arrays.** `wp option update` and
   `wp post meta update` store JSON strings, not PHP arrays. Use
   `update_option()`, `set_theme_mod()`, `update_post_meta()` through
   `wp eval`/`wp eval-file`, or the bridge.
3. **Typography must be complete.** A `ct-typography` value needs `family`,
   `variation`, `size`, `line-height`, `letter-spacing`, `text-transform`, and
   `text-decoration`. A partial object produces warnings and broken CSS.
4. **Responsive values need all devices.** Use
   `{"desktop": ..., "tablet": ..., "mobile": ...}`. Do not rely on missing
   keys being filled.
5. **Content Blocks need conditions.** An empty `conditions` array means "never
   display". Selection is newest matching block first; avoid overlapping blocks
   for the same template type.
6. **Refresh the caches after a write.**
   `do_action('blocksy:dynamic-css:refresh-caches')` regenerates
   `uploads/blocksy/css/global.css`; `do_action('blocksy:cache-manager:purge-all')`
   clears page/object caches.
7. **Backup, then dry-run, then apply, then verify.** A real apply validates
   the whole plan first and writes nothing if any part is invalid, but there is
   no database transaction. Export current settings first and keep the backup
   until the site is verified. To undo an applied plan, use
   `node scripts/remote.mjs restore backup.json` or `scripts/restore-plan.mjs`
   (`references/verification.md`).
8. **Check the free/pro tier before activating an extension.** Pro extensions
   are silently unavailable on the free plugin. See
   `references/extensions.md`.
9. **Stop at a Pro gate. Ask for Pro, do not bypass it.** If the request needs a
   Pro-only feature and the site has the free Companion build (or no valid
   licence), stop before composing/applying a plan and ask the user to install
   and activate Blocksy Companion Pro. Do not fake, patch, emulate, or silently
   substitute the feature. See `references/pro-gate.md`.

## Pro gate

This is the one rule that overrides "make it work":

- Free build detected (`companion_build: free`, `premium_code: false`,
  `plan: free`) and the request needs a Pro extension, Content Blocks, extra
  header/footer sections, Pro builder items, or Pro fonts → **stop**.
- Tell the user exactly what is Pro-only and that Pro replaces the free
  Companion plugin (only one can be active).
- Ask them to install and activate Blocksy Companion Pro and its licence.
- After they confirm, re-run `info`/`schema` and verify `companion_build: pro`,
  `premium_code: true`, and the requested extension is `available: true`.
- Then continue.
- If they decline, offer a free-scope alternative **only with explicit
  consent**, and label it as a different design, not a workaround.

Never write `blocksy_active_extensions` by hand to fake activation, never
activate both Companion plugins, never patch licence checks, and never recreate
a Pro feature with custom code. Full policy and feature list:
`references/pro-gate.md`.

## Building pages with another skill

When another skill (GreenLight/GreenShift, core blocks, any block suite) writes
the page content, this skill supplies the design system and the page settings:

1. Export live tokens: `node scripts/remote.mjs tokens > blocksy-tokens.json`
   or `BLOCKSY_INSPECT=tokens ... eval-file scripts/inspect.php`.
2. Give the block skill `blocksy-tokens.json` plus the rules in
   `references/design-tokens.md`: palette slugs/`var(--theme-palette-color-N)`
   instead of hex, inherited fonts, Blocksy widths, breakpoints
   999.98px / 689.98px, no `--theme-*` overrides at `:root`.
3. Apply the per-page layout meta (full width, no hero, no content spacing)
   with a plan `post_meta` section.
4. Header and footer stay in the builder (`references/builder.md`); never
   rebuild them as page blocks.

`data/css-variables.json` and `data/css-classes.json` are the static catalog
(Blocksy 2.1.60) for offline use.

## The plan format

A plan is a JSON object. Only include the sections you need.

```json
{
  "version": 1,
  "extensions": {
    "activate": ["cookies-consent"],
    "deactivate": []
  },
  "theme_mods": {
    "colorPalette": { "color1": { "color": "#2563eb" } },
    "header_placements": { "current_section": "type-1", "sections": [] }
  },
  "remove_theme_mods": [],
  "options": {
    "blocksy_ext_custom_fonts_settings": { "fonts": [], "stacks": [] }
  },
  "remove_options": [],
  "menus": [
    {
      "name": "Main Menu",
      "location": "menu_1",
      "replace": true,
      "items": [
        { "key": "home", "title": "Home", "type": "custom", "url": "/" }
      ]
    }
  ],
  "content_blocks": [
    {
      "key": "single-notice",
      "title": "Single Notice",
      "template_type": "hook",
      "status": "publish",
      "content": "<!-- wp:paragraph --><p>Notice</p><!-- /wp:paragraph -->",
      "meta": {
        "conditions": [
          { "type": "include", "rule": "single_post", "payload": [] }
        ],
        "location": "blocksy:content:top",
        "priority": 10
      }
    }
  ],
  "post_meta": {
    "sample-page": { "page_structure_type": "type-2" }
  },
  "remove_post_meta": {
    "sample-page": ["page_structure_type"]
  },
  "cache": true
}
```

Full reference: `references/plan-format.md`.
One working example: `examples/example-plan.json`.

## Workflow

### 1. Inspect

WP-CLI:

```sh
# Small: theme, versions, licence plan, extensions, menu locations. Read this first.
BLOCKSY_INSPECT=info ./scripts/wp-local.sh /path/to/site/app/public eval-file scripts/inspect.php

# Large (tens of thousands of lines): save to a file, never print it.
BLOCKSY_INSPECT=schema ./scripts/wp-local.sh /path/to/site/app/public eval-file scripts/inspect.php > schema.json
```

Remote:

```sh
BLOCKSY_URL=https://example.com BLOCKSY_TOKEN='...' \
  node scripts/remote.mjs info

BLOCKSY_URL=https://example.com BLOCKSY_TOKEN='...' \
  node scripts/remote.mjs schema > schema.json
```

`info` tells you the active theme, whether the child is active, Blocksy and
Companion versions, licence plan, active extensions, CSS mode, and menu
locations. `schema` is the live catalog for **this** install.

Do not read `schema.json` or the `data/` catalogs whole. Look options up:

```sh
node scripts/find-option.mjs sticky --in builder --schema schema.json
node scripts/find-option.mjs --id rootTypography --json --schema schema.json
node scripts/find-option.mjs "site width"            # no --schema: bundled 2.1.60 snapshot
```

Each match shows where the option lives (`theme_mods`, a header/footer item, `post_meta`, a Content Block type), its type, whether it is responsive, and its default. Labels are English regardless of the site language.

### 2. Back up

```sh
# WP-CLI
BLOCKSY_INSPECT=export BLOCKSY_INSPECT_PORTABLE=1 BLOCKSY_INSPECT_POST_META=1 \
  ./scripts/wp-local.sh /path/to/site/app/public eval-file scripts/inspect.php > backup.json

# Remote
BLOCKSY_URL=https://example.com BLOCKSY_TOKEN='...' \
  node scripts/remote.mjs export --portable --post-meta > backup.json
```

Keep `backup.json` until the site is verified.

### 3. Compose the plan

Use the live schema for valid IDs, types, and defaults (`scripts/find-option.mjs`). Start from
`examples/example-plan.json` and edit it. See:

- `references/theme-options.md` for value shapes
- `references/builder.md` for header/footer placement structures
- `references/content-blocks.md` for template types, conditions, hooks, popups
- `references/extensions.md` for extension IDs, tiers, storage, and settings
- `references/menus.md` for menu items and locations

### 4. Dry-run, apply, verify

```sh
# WP-CLI dry-run
BLOCKSY_PLAN=plan.json BLOCKSY_DRY_RUN=1 \
  ./scripts/wp-local.sh /path/to/site/app/public eval-file scripts/apply.php

# WP-CLI apply
BLOCKSY_PLAN=plan.json \
  ./scripts/wp-local.sh /path/to/site/app/public eval-file scripts/apply.php

# Remote dry-run
BLOCKSY_URL=https://example.com BLOCKSY_TOKEN='...' \
  node scripts/remote.mjs apply plan.json --dry-run

# Remote apply
BLOCKSY_URL=https://example.com BLOCKSY_TOKEN='...' \
  node scripts/remote.mjs apply plan.json
```

A successful apply returns `ok: true`, the action list, warnings, errors, and
cache results. Then follow `references/verification.md`.

## Adapters in one page

### WP-CLI

Use `scripts/wp-local.sh`. It picks the runtime from the site path:

- **DDEV** (`.ddev/config.yaml` in the site dir or a parent): runs WP-CLI in
  the web container. Never starts a stopped project. Back up with
  `ddev snapshot` (real DB rollback). Details: `references/ddev.md`.
- **LocalWP**: discovers the MySQL socket by matching the site path in
  `~/.config/Local/run/*/conf/nginx/site.conf`.
- Otherwise plain `wp --path=...`.

```sh
./scripts/wp-local.sh <site-root> <wp command>
```

### Bridge REST

1. Upload `dist/blocksy-bridge.zip` in **Plugins → Add New → Upload Plugin**.
2. Activate it.
3. Open **Settings → Blocksy Bridge** and copy the token.
4. Use `scripts/remote.mjs` with `BLOCKSY_URL` and `BLOCKSY_TOKEN`.

Application Passwords are supported as the preferred auth. The token is the
fallback for hosts where the standard `Authorization` header is stripped
(common on minimal nginx/LocalWP configs) or app passwords are disabled. The
client sends it as `X-Blocksy-Bridge-Token`; set `BLOCKSY_TOKEN_QUERY=1` only if
a host strips custom headers too.

### Core REST fallback (no plugin install)

Core REST can handle menus and page/post content, and the theme exposes
`blocksy_meta` for per-page settings. It **cannot** set global theme mods, the
builder, extension options, or a Content Block's `template_type`. Use it only
for the subset it supports; use manual import for the rest.

### Manual / assisted

Generate the plan and either:

- import the theme options through **Customizer → General → Manage Options →
  Import**, or
- paste a generated PHP apply snippet into a code-snippets plugin, or
- create the Content Blocks and menus manually from the plan.

## What lives where

| Layer | Storage |
| --- | --- |
| Theme + child options | theme mods of the active stylesheet |
| Header/footer builder | `header_placements` / `footer_placements` theme mods |
| Active extensions | `blocksy_active_extensions` option |
| Extension dashboard settings | `blocksy_ext_*` options |
| Extension customizer settings | theme mods of the active theme |
| Content Blocks / popups / templates | `ct_content_block` posts + `template_type` meta + `blocksy_post_meta_options` meta |
| Per-page settings | `blocksy_post_meta_options` post meta |
| Menus | core WordPress menus + `nav_menu_locations` theme mod |
| CSS | `uploads/blocksy/css/global.css` + `blocksy_dynamic_styles_descriptor` transient |

Details: `references/storage-model.md`.

## Data files

| File | Contents |
| --- | --- |
| `data/theme-options.json` | 674 theme options for Blocksy 2.1.60: ID, type, default, responsive, section, choices |
| `data/builder-options.json` | 24 header + 20 footer items, 903 item options, 12 header + 8 footer section settings, default placements |
| `data/post-meta-options.json` | Per-post/page/blog meta options |
| `data/content-block-options.json` | Content Block options for all 9 template types |
| `data/builder-items.json` | Every header/footer builder item with tier (free/pro), required extension or plugin |
| `data/css-variables.json` | Catalog of Blocksy `--theme-*` CSS variables |
| `data/css-classes.json` | Catalog of Blocksy utility and structural CSS classes |

These are **snapshots**. Always prefer the live `schema` from the target site.
Version differences are real; the extractor is part of the bridge and
`scripts/inspect.php`.

## Safety

- Only administrators can use the bridge. Do not expose the token in frontend
  code, commits, screenshots, or chat logs.
- Prefer Application Passwords over the query-string token in production.
- The bridge refuses arbitrary option keys, arbitrary post types, arbitrary PHP,
  plugin activation, and user management.
- Run `--dry-run` first. Read warnings. Check the returned action list.
- If a plan error mentions an unknown theme mod or option, the target site's
  Blocksy version or active extensions differ from the catalog. Re-inspect
  instead of guessing.
- When the work is finished on a production site, deactivate and delete the Blocksy Bridge plugin (or at least regenerate its token in Settings → Blocksy Bridge) and revoke the Application Password. The token is administrator-equivalent.

## References

| File | Read it for |
| --- | --- |
| `references/adapters.md` | WP-CLI, bridge REST, core REST, manual fallback, auth, installation |
| `references/ddev.md` | DDEV projects: container WP-CLI, snapshots, uploads paths, prod DB import, mkcert TLS for the bridge client |
| `references/plan-format.md` | Every plan field and its semantics |
| `references/storage-model.md` | Exact database/API location of every setting |
| `references/theme-options.md` | Control value shapes and global theme options |
| `references/builder.md` | Header/footer structure, complete item inventory (27 header, 20 footer), free/pro/extension requirements |
| `references/design-tokens.md` | Palette, typography, layout, breakpoints, CSS variables/classes for skills that build block pages; GreenLight mapping |
| `references/content-blocks.md` | Template types, conditions, hooks, popups, maintenance |
| `references/extensions.md` | All 15 extensions, free/pro, plans, storage, settings |
| `references/pro-gate.md` | Stop/ask/verify policy when a Pro-only feature is requested on a free build |
| `references/menus.md` | Menus, items, locations, mega-menu meta |
| `references/verification.md` | Post-apply checks and cleanup |
Pliki w paczce (4)
  • .gitignore 1 KB
  • LICENSE 1 KB
  • README.md 5 KB
  • SKILL.md 16 KB

Wersje

W bazie nie ma innych skilli o nazwie blocksy.

Migawka bazy z 13.11.2026 · wersja paczki b71e507d34f7 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95wordpress-developer
    Pomaga tworzyć motywy, wtyczki i bloki WordPress: theme.json, Gutenberg, REST API, hooki i WP-CLI.
  • 100html-to-block-theme
    Zamienia statyczne projekty HTML, CSS i JS lub istniejącą stronę w blokowy motyw WordPress, gotowy do użycia jako prawdziwa witryna.
  • 90figma-to-gutenberg
    Odtwarza ramkę z Figmy w WordPressie z edytorem blokowym: mapuje węzły na bloki core Gutenberga, rejestruje paletę w Global Styles i zapisuje do wersji roboczej.
  • 100wp-block-theme-converter
    Zamienia statyczną stronę HTML, CSS i JS w motyw blokowy WordPressa z theme.json, szablonami FSE i wzorcami bloków.
  • 95wp-block-editor
    Pomaga tworzyć bloki Gutenberg w WordPressie: pliki block.json, edycję i zapis bloków, stan edytora i rozszerzanie bloków.
  • 90wordpress-wordpress-router
    Rozpoznaje repozytorium WordPress, czyli plugin, motyw, blok lub rdzeń, i kieruje do właściwego przepływu pracy.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.