An absolute path is a path that starts from the root of the filesystem. For example, /home/user/my-hyde-project/_pages/example.md is an absolute path. These should only be used as the last step of a filesystem operation, for example just before writing, reading, or creating a file.
Hyde prefers relative paths. These are paths that are relative to the project root (or a subdirectory therein). For example, _pages/example.md is a relative path. These should be used as much as possible, as they are more portable and easier to work with.
Now that the path types are defined, let's set up some examples for the rest of this document.
The project root is simply the directory that contains all the project files.
Our project root is /home/user/my-hyde-project. Almost all paths used will be relative to this directory. For example, if we are talking about _pages/example.md, we are really talking about /home/user/my-hyde-project/_pages/example.md.
The project directory is the directory that contains all the project files. This is the same as the project root.
Source directories are directories that contain source files. The directory (and in cases of _pages/ also the file extension) lets Hyde know what type of page to parse the source file as. For example, if you put a Markdown file in the _posts directory, Hyde will know to parse it as a MarkdownPage object and use the Blade templates for post, and that the page should be output to the _site/posts directory.
The source directories are:
- _media
- _pages
- _posts
- _docs
The output directory is the directory that Hyde will output the generated site to. By default, this is the _site directory.
Nested directories are directories that are nested within the their relative scope. Simply put, a nested directory in Hyde is a source directory that contains a subdirectory. For example, if you have a directory inside the _pages directory, that's a nested directory. This term can also apply to output directories, but it's not as common.
HydePHP follows the MDN description of URLs which can be visualized using their graphic (CC-BY-SA):
When we talk about paths, we are talking about the actual file paths on the filesystem. When we talk about links, we are talking about the URL that the user will see in their browser.
When we talk about just links, we are talking about the URL path that the user will see in their browser. Unless it's specified wether a link is relative or absolute, it's assumed to be relative to the index page of the site and will not contain a leading slash nor path traversal directives,
When links are relative, they are always relative to the page that is currently being visited. If there is no information about the page being visited, they are relative to the root of the site. The relative information is denoted by a set of path traversal directives (../) and are automatically generated by Hyde when resolving links.
Absolute links (or root-relative links) are links that start from the root of the site. For example, /about is an absolute link. These are generally discouraged in Hyde, as they are not portable and can cause issues when moving the site to a different domain or subdirectory. They also break local browsing when not using a web server, and are thus not used for links in Hyde generated HTML (but can of course be specified by the user).
Qualified (URI/URL) links are absolute links that include the project's configured base URL. When a base URL is available, it is used for links where such a type is preferred, such as canonical meta tags, and RSS feeds, and the sitemap.
Pretty links are links that do not include the file extension. For example, about is a pretty link, while about.html is not. Pretty links are disabled by default, but can be enabled in the project configuration. When enabled, some pages may also be rewritten, for example index.html will be rewritten to /.
Now that we have the basics out of the way, let's get into the specifics AKA the more interesting stuff.
The identifier is the part between the source directory and the file extension It may also be known as a 'slug', or previously 'basename'.
For example, the identifier of a source file stored as '_pages/about/contact.md' would be 'about/contact', and 'pages/about.md' would simply be 'about'.
An identifier never contains the file extension, and is always relative to the source directory (which is thus also not included).
The route key is the URL path relative to the site root. Route keys are very important in Hyde as they map the correlation between a source file and the eventual HTTP endpoint that will resolve to the static HTML file.
For example, if the compiled page will be saved to _site/docs/index.html, then the route key will be 'docs/index'. Route keys are used to identify pages, similar to how named routes work in Laravel.
Route keys are always relative to the site root, and never contain the file extension (as they always refer to HTML pages).
-
$sourcePath- Generally a local file path for the page source file relative to the project root. -
$outputPath- Generally an output file path relative to the _site output directory. -
$filename- The full name of a file (without path information). In other words, it's a slug with a file extension. Example:hello-world.md -
$filepath- The full file path (almost always relative to the root of the Hyde project installation). Includes the file extension. Example:_posts/hello-world.md
Text in [brackets] show data that is implied by the context, but are not a part of the value itself.
[_posts/]hello-world[.md]
[_posts/]hello-world.md
_posts/hello-world.md
posts/hello-world
[_site/]posts/hello-world.html