Skip to content

[3.x] New publish command #2500

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
emmadesilva wants to merge 18 commits into
base: v3-dev
Choose a base branch
from
+3,291 −614
Draft

[3.x] New publish command #2500

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
28deee9
Create new-publish-command-spec.md
emmadesilva Jul 4, 2026
f62a7b5
Create new-publish-command-implementation-plan.md
emmadesilva Jul 4, 2026
81de9b5
Update new-publish-command-spec.md
emmadesilva Jul 4, 2026
9cfc01a
Step 1: Add OverwritePolicy service and OverwriteAction enum
emmadesilva Jul 4, 2026
9c87808
Step 2: Add publishable page registry
emmadesilva Jul 4, 2026
8b549c9
Step 2: Remove blank starter default target
emmadesilva Jul 4, 2026
e84e4d0
Step 3: Add PublishCommand guardrails
emmadesilva Jul 4, 2026
fdba13b
Step 4: Implement the views publishing flow
emmadesilva Jul 4, 2026
1318406
Step 5: Implement the pages publishing flow
emmadesilva Jul 4, 2026
bad493a
Step 5: Streamline page destination prompt
emmadesilva Jul 4, 2026
76a64e8
Step 5: Pin multi-select --to guard precedence
emmadesilva Jul 4, 2026
ddcda1c
Step 6: Register the hyde-config publish tag
emmadesilva Jul 4, 2026
b4829a6
Step 7: Convert the old publish commands into deprecated aliases
emmadesilva Jul 4, 2026
655d622
Step 8: Align docs with the new publish command surface
emmadesilva Jul 4, 2026
53d257c
Step 9: Acceptance sweep — pin --all-is-views-only (§11)
emmadesilva Jul 4, 2026
f545e79
Apply fixes from StyleCI
StyleCIBot Jul 4, 2026
58785a5
Fix publish views invalid group handling
emmadesilva Jul 4, 2026
c4c8a66
Cover remaining publish feature paths in tests
emmadesilva Jul 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/creating-content/managing-assets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ To make it really easy to customize asset loading, the styles and scripts are lo
To customize them, run the following command:

```bash
php hyde publish:views layouts
php hyde publish --layouts
```

Then edit the files found in `resources/views/vendor/hyde/layouts` directory of your project.
Expand Down
4 changes: 2 additions & 2 deletions docs/digging-deeper/advanced-markdown.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ coloured blockquotes. Simply append the desired colour after the initial `>` cha
You can easily customize these styles by publishing and editing the `markdown-blockquote.blade.php` file.

```bash
php hyde publish:views components
php hyde publish --components
```

### Markdown usage
Expand Down Expand Up @@ -166,7 +166,7 @@ You can enable it for other page types by adding the page class to the `permalin
Under the hood, Hyde uses a custom Blade-based heading renderer when converting Markdown to HTML. This allows for more flexibility and customization compared to standard Markdown parsers. You can also publish and customize the Blade component used to render the headings:

```bash
php hyde publish:components
php hyde publish --components
```

This will copy the `markdown-heading.blade.php` component to your views directory where you can modify its markup and behavior.
Expand Down
11 changes: 7 additions & 4 deletions docs/digging-deeper/customization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ The main configuration file, `hyde.php`, is used for things ranging from site na

Since HydePHP is based on Laravel we also have a few configuration files related to them. As you most often don't need
to edit any of these, unless you want to make changes to the underlying application, they are not present in the
base HydePHP installation. However, you can publish them to your project by running `php hyde publish:configs`.
base HydePHP installation. However, you can publish them to your project by running `php hyde vendor:publish --tag=hyde-config`.

| Config File | Description |
|------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
Expand All @@ -92,7 +92,7 @@ base HydePHP installation. However, you can publish them to your project by runn

{.align-top}

If any of these files are missing, you can run `php hyde publish:configs` to copy the default files to your project.
If any of these files are missing, you can run `php hyde vendor:publish --tag=hyde-config` to copy the default files to your project.

## Configuration Options

Expand Down Expand Up @@ -371,12 +371,15 @@ instead the appropriate color scheme will be automatically applied based on the
Hyde uses the Laravel Blade templating engine. Most parts of the included templates have been extracted into components to be customized easily.
Before editing the views you should familiarize yourself with the [Laravel Blade Documentation](https://laravel.com/docs/10.x/blade).

To edit a default Hyde component you need to publish them first using the `hyde publish:views` command.
To edit a default Hyde component you need to publish them first using the `hyde publish` command.

```bash
php hyde publish:views
php hyde publish --all
```

You can also run `php hyde publish` without any flags to interactively pick which views to publish,
or scope the command to just `--layouts` or `--components`.

The files will then be available in the `resources/views/vendor/hyde` directory.

>info **Tip:** If you use Linux/macOS or Windows with WSL you will be able to interactively select individual files to publish.
Expand Down
4 changes: 2 additions & 2 deletions docs/digging-deeper/helpers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -333,8 +333,8 @@ HydePHP comes with a started homepage called 'posts'. This includes a component

#### Creating our posts page

Now, let's paginate this feed! For this example, we will assume that you ran `php hyde publish:homepage posts`
and renamed the resulting `index.blade.php` file to `posts.blade.php`. We will also assume that you have a few blog posts set up.
Now, let's paginate this feed! For this example, we will assume that you ran `php hyde publish --page=posts`
to publish the posts feed page to `_pages/posts.blade.php`. We will also assume that you have a few blog posts set up.

The blog post feed component is a simple component that looks like this:

Expand Down
4 changes: 2 additions & 2 deletions docs/digging-deeper/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,13 +76,13 @@ You can read more about some of these in the [Core Concepts](core-concepts#paths
| Wrong layout used | Hyde determines the layout template to use depending on the directory of the source file | Ensure your source file is in the right directory. |
| Invalid/no permalinks or post URIs | You may be missing or have an invalid site URL | Set the site URL in the `.env` file |
| No styles in custom Blade pages | When using custom blade pages need to add the styles yourself. You can do this by extending the default layout | Use the app layout, or by include the Blade components directly. |
| Overriding Hyde views is not working | Ensure the Blade views are in the correct directory. | Rerun `php hyde publish:views`. |
| Overriding Hyde views is not working | Ensure the Blade views are in the correct directory. | Rerun `php hyde publish --all`. |
| Styles not updating when deploying site | It could be a caching issue. To be honest, when dealing with styles, it's always a caching issue. | Clear your cache, and optionally complain to your site host |
| Documentation sidebar items are in the wrong order | Double check the config, make sure the route keys are written correctly. Check that you are not overriding with front matter. | Check config for typos and front matter |
| Issues with date in blog post front matter | The date is parsed by the PHP `strtotime()` function. The date may be in an invalid format, or the front matter is invalid | Ensure the date is in a format that `strtotime()` can parse. Wrap the front matter value in quotes. |
| RSS feed not being generated | The RSS feed requires that you have set a site URL in the Hyde config or the `.env` file. Also check that you have blog posts, and that they are enabled. | Check your configuration files. | |
| Sitemap not being generated | The sitemap requires that you have set a site URL in the Hyde config or the `.env` file. | Check your configuration files. | |
| Unable to do literally anything | If everything is broken, you may be missing a Composer package or your configuration files could be messed up. | Run `composer install` and/or `composer update`. If you can run HydeCLI commands, update your configs with `php hyde publish:configs`, or copy them manually from GitHub or the vendor directory. |
| Unable to do literally anything | If everything is broken, you may be missing a Composer package or your configuration files could be messed up. | Run `composer install` and/or `composer update`. If you can run HydeCLI commands, update your configs with `php hyde vendor:publish --tag=hyde-config`, or copy them manually from GitHub or the vendor directory. |
| Namespaced Yaml config (`hyde.yml`) not working | When using namespaced Yaml configuration, you must begin the file with `hyde:`, even if you just want to use another file for example `docs:`. | Make sure the file starts with `hyde:` (You don't need to specify any options, as long as it's present). See [`#1475`](https://github.com/hydephp/develop/issues/1475) |

### Extra troubleshooting information
Expand Down
6 changes: 3 additions & 3 deletions docs/digging-deeper/updating-hyde.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,14 +89,14 @@ composer update
Then, update your config files. This is the hardest part, as you may need to manually copy in your own changes.

```bash
php hyde publish:configs
php hyde vendor:publish --tag=hyde-config
```

If you have published any of the included Blade components you will need to re-publish them.

```bash
php hyde publish:views layouts
php hyde publish:views components
php hyde publish --layouts
php hyde publish --components
```

You may also want to download any resources that have been updated. You download these from the Zip file of the latest release on GitHub.
Expand Down
77 changes: 40 additions & 37 deletions docs/getting-started/console-commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,8 @@ Here is a quick reference of all the available commands. You can also run `php h
| [`build:sitemap`](#build-sitemap) | Generate the `sitemap.xml` file |
| [`make:page`](#make-page) | Scaffold a new Markdown, Blade, or documentation page file |
| [`make:post`](#make-post) | Scaffold a new Markdown blog post file |
| [`publish:configs`](#publish-configs) | Publish the default configuration files |
| [`publish:homepage`](#publish-homepage) | Publish one of the default homepages as `index.blade.php` |
| [`publish:views`](#publish-views) | Publish the hyde components for customization. Note that existing files will be overwritten |
| [`vendor:publish`](#vendor-publish) | Publish any publishable assets from vendor packages |
| [`publish`](#publish) | Publish Hyde views and starter pages for customization |
| [`vendor:publish`](#vendor-publish) | Publish any publishable assets from vendor packages (including the Hyde config files) |
| [`route:list`](#route-list) | Display all registered routes |
| [`validate`](#validate) | Run a series of tests to validate your setup and help you optimize your site |
| [`list`](#available-commands) | List all available commands |
Expand Down Expand Up @@ -172,48 +170,35 @@ Scaffold a new Markdown blog post file
| `title` | The title for the Post. Will also be used to generate the filename |
| `--force` | Should the generated file overwrite existing posts with the same filename? |

## Publish the Default Configuration Files
## Publish Hyde views and starter pages for customization

<a name="publish-configs" style="display: inline-block; position: absolute; margin-top: -5rem;"></a>
<a name="publish" style="display: inline-block; position: absolute; margin-top: -5rem;"></a>

```bash
php hyde publish:configs
php hyde publish [--layouts] [--components] [--all] [--page[=NAME]] [--to=PATH] [--force]
```

Publish the default configuration files
Publish Hyde views and starter pages for customization.

## Publish one of the default homepages as `index.blade.php`.
With no flags, `publish` runs an interactive wizard that lets you choose between publishing
**views** (Hyde's Blade layouts and components) or **a starter page** (such as a homepage or 404 page).
Each flag simply skips a step of the wizard. Existing files that you have modified are never overwritten
without your confirmation or the `--force` flag.

<a name="publish-homepage" style="display: inline-block; position: absolute; margin-top: -5rem;"></a>

```bash
php hyde publish:homepage [--force] [--] [<homepage>]
```

Publish one of the default homepages as `index.blade.php`.

#### Arguments & Options

| | |
|------------|---------------------------------|
| `homepage` | The name of the page to publish |
| `--force` | Overwrite any existing files |

## Publish the hyde components for customization

<a name="publish-views" style="display: inline-block; position: absolute; margin-top: -5rem;"></a>

```bash
php hyde publish:views [<group>]
```
#### Options

Publish the hyde components for customization. Note that existing files will be overwritten.
| Option | Description |
|----------------|--------------------------------------------------------------|
| `--layouts` | Scope publishing to the Hyde layout views |
| `--components` | Scope publishing to the Hyde component views |
| `--all` | Publish all Hyde views without the picker |
| `--page[=NAME]`| Publish a starter page, optionally by name (e.g. `--page=welcome`) |
| `--to=PATH` | Destination path for a published page (pages only) |
| `--force` | Overwrite files that you have modified |

#### Arguments
Published views land in `resources/views/vendor/hyde`, and published pages land in `_pages`.

| | |
|----------|-------------------------|
| `group` | The group to publish |
>info **Tip:** To publish the Hyde configuration files, use `php hyde vendor:publish --tag=hyde-config`. See the [`vendor:publish`](#vendor-publish) command below.

## Display All Registered Routes.

Expand All @@ -233,7 +218,14 @@ Display all registered routes.
php hyde vendor:publish [--existing] [--force] [--all] [--provider [PROVIDER]] [--tag [TAG]]
```

Publish any publishable assets from vendor packages
Publish any publishable assets from vendor packages. This is the advanced Laravel publishing path,
and is also where the Hyde configuration files are published from, using the `hyde-config` tag:

```bash
php hyde vendor:publish --tag=hyde-config
```

This publishes the Hyde-owned config files (`hyde.php`, `docs.php`, `markdown.php`, `view.php`, `cache.php`, and `commands.php`) to your project's `config` directory.

#### Options

Expand All @@ -244,3 +236,14 @@ Publish any publishable assets from vendor packages
| `--all` | Publish assets for all service providers without prompt |
| `--provider=` | The service provider that has assets you want to publish |
| `--tag=` | One or many tags that have assets you want to publish \n- Is multiple: yes |

## Deprecated publishing commands

The following commands from earlier versions of Hyde still work but are deprecated, and print a notice
pointing to their replacement. They will be removed in a future major version, so prefer the new commands.

| Deprecated command | Use instead |
|-------------------------------|----------------------------------------------------|
| `publish:views [group]` | `publish --layouts` / `publish --components` |
| `publish:configs` | `vendor:publish --tag=hyde-config` |
| `publish:homepage [template]` | `publish --page=[template]` |
Loading