Skip to content

Commit

Permalink
Remove hard line breaks from sections
Browse files Browse the repository at this point in the history
  • Loading branch information
@caendesilva
caendesilva committed Jul 12, 2024
1 parent d4836ee commit 51dc2ed
Showing 1 changed file with 29 additions and 61 deletions.
90 changes: 29 additions & 61 deletions docs/creating-content/documentation-pages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,17 @@ navigation:

## Introduction to Hyde Documentation Pages

Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier.
Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest.
Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest.

Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a
responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order,
labels, and even groups, of the sidebar items to suit your needs.
Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and even groups, of the sidebar items to suit your needs.

Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated
"Docs" link will be added to your site's main navigation menu, pointing to your documentation page.
Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page.

If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically,
saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight).
If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight).

### Best Practices and Hyde Expectations

Since Hyde does a lot of things automatically, there are some things you may need
to keep in mind when creating blog posts so that you don't get unexpected results.
Since Hyde does a lot of things automatically, there are some things you may need to keep in mind when creating blog posts so that you don't get unexpected results.

#### Filenames

Expand Down Expand Up @@ -77,13 +71,11 @@ navigation:

## Dynamic Content Generation

Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title.
If you are not happy with the results you can customize them in the config or with front matter.
Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. If you are not happy with the results you can customize them in the config or with front matter.

### Front Matter reference

Before we look at how to override things, here is an overview of the relevant content Hyde generates,
and where the data is from as well as where it can be overridden.
Before we look at how to override things, here is an overview of the relevant content Hyde generates, and where the data is from as well as where it can be overridden.

| Property | Description | Dynamic Data Source | Override in |
|---------------------------------|--------------------------------------------------------|-------------------------------------|----------------------|
Expand All @@ -95,29 +87,26 @@ and where the data is from as well as where it can be overridden.

## Sidebar

The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order
of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings.
The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings.

Since this feature shares a lot of similarities and implementation details with the navigation menu,
I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology.
Since this feature shares a lot of similarities and implementation details with the navigation menu, I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology.

### Sidebar ordering

The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be.
The default priority is 999. You can override the priority using the following front matter:
The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter:

```yaml
navigation:
priority: 5
```
You can also change the order in the Docs configuration file.
See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. <br>
You can also change the order in the Docs configuration file. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. <br>
_I personally think the config route is easier as it gives an instant overview, however the first way is nice as well._
### Sidebar labels
The sidebar items are labelled with the `label` property. The default label is the filename of the file.

You can change it with the following front matter:

```yaml
Expand All @@ -127,12 +116,9 @@ navigation:

### Sidebar grouping

Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items.
The Hyde docs for instance use this.
Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. The Hyde docs for instance use this.

The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set
in the front matter, or when subdirectories are used. This will then switch to a slightly more compact sidebar layout with pages sorted into categories.
Any pages without the group front matter will get put in the "Other" group.
The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set in the front matter, or when subdirectories are used. This will then switch to a slightly more compact sidebar layout with pages sorted into categories. Any pages without the group front matter will get put in the "Other" group.

### Sidebar footer customization

Expand Down Expand Up @@ -182,13 +168,12 @@ This can be useful to create redirects or other items that should not be shown i

## Customization

Please see the [customization page](customization) for in-depth information on how to customize Hyde,
including the documentation pages. Here is a high level overview for quick reference though.
Please see the [customization page](customization) for in-depth information on how to customize Hyde, including the documentation pages. Here is a high level overview for quick reference though.

### Output directory

If you want to store the compiled documentation pages in a different directory than the default 'docs' directory,
for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file.
If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file.

The path is relative to the site output, typically `_site`.

```php
Expand All @@ -207,17 +192,15 @@ By default, a link to the documentation page is added to the navigation menu whe

### Sidebar header name

By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs".
You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists.
By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists.

```php
'title' => 'API Documentation',
```

### Sidebar page order

To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order.
Link items without an entry here will fall back to the default priority of 999, putting them last.
To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. Link items without an entry here will fall back to the default priority of 999, putting them last.

```php
'sidebar' => [
Expand All @@ -233,9 +216,7 @@ See [the chapter in the customization page](customization#navigation-menu--sideb

### Automatic sidebar group labels

When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names.
If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file.
The array key is the directory name, and the value is the label.
When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. The array key is the directory name, and the value is the label.

Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself!

Expand All @@ -251,8 +232,7 @@ Please note that this option is not added to the config file by default, as it's

Hyde automatically generates a table of contents for the page and adds it to the sidebar.

In the `config/docs.php` file you can configure the behaviour, content, and the look and feel of the sidebar table of contents.
You can also disable the feature completely.
In the `config/docs.php` file you can configure the behaviour, content, and the look and feel of the sidebar table of contents. You can also disable the feature completely.

```php
'sidebar' => [
Expand All @@ -266,9 +246,7 @@ You can also disable the feature completely.

### Using flattened output paths

If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory.
This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure.
Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other.
If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure. Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other.

If you set this to false, Hyde will match the directory structure of the source files (just like all other pages).

Expand All @@ -281,8 +259,7 @@ If you set this to false, Hyde will match the directory structure of the source

### Introduction

The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator
that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget.
The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget.

>info Tip: The HydeSearch plugin is what powers the search feature on this site! Why not [try it out](search)?

Expand All @@ -301,16 +278,13 @@ The search works by generating a JSON search index which the JavaScript plugin l

Two ways to access the search are added, one is a full page search screen that will be saved to `docs/search.html`.

The second method is a button added to the documentation pages, similar to how Algolia DocSearch works.
Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`.
The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`.

>info The full page can be disabled by setting `create_search_page` to `false` in the `docs` config.

### Hiding pages from indexing

If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index.
You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how
navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file.
If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file.

```php
// filepath: config/docs.php
Expand All @@ -327,13 +301,9 @@ The Realtime Compiler that powers the `php hyde serve` command will automaticall

### Introduction

Hyde can automatically add links to documentation pages that take the user
to a GitHub page (or similar) to edit the page. This makes it great for open-source projects
looking to allow others to contribute to the documentation in a quick and easy manner.
Hyde can automatically add links to documentation pages that take the user to a GitHub page (or similar) to edit the page. This makes it great for open-source projects looking to allow others to contribute to the documentation in a quick and easy manner.

The feature is automatically enabled when you specify a base URL in the Docs configuration file.
Hyde expects this to be a GitHub path, but it will probably work with other methods as well,
if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)!
The feature is automatically enabled when you specify a base URL in the Docs configuration file. Hyde expects this to be a GitHub path, but it will probably work with other methods as well, if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)!

>info Tip: This documentation site uses this feature, scroll down to the bottom of this page and try it out!

Expand All @@ -358,8 +328,7 @@ Changing the label is easy, just change the following config setting:

#### Changing the position

By default, the button will be shown in both the documentation page footer.
You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'`
By default, the button will be shown in both the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'`

```php
// Filepath: config/docs.php
Expand All @@ -368,8 +337,7 @@ You can change this by setting the following config setting to `'header'`, `'foo

#### Adding a button icon

This is not included out of the box, but is easy to add with some CSS!
Just target the `.edit-page-link` class.
This is not included out of the box, but is easy to add with some CSS! Just target the `.edit-page-link` class.

```css
// filepath e.g. app.css
Expand Down

0 comments on commit 51dc2ed

Please sign in to comment.