From ec616b5837a570d5d1837a6e80895a57bff6b89d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 13 Mar 2023 19:00:24 +0100 Subject: [PATCH 1/4] Delete draft-internal-glossary.markdown --- .../internal/draft-internal-glossary.markdown | 130 ------------------ 1 file changed, 130 deletions(-) delete mode 100644 docs/internal/draft-internal-glossary.markdown diff --git a/docs/internal/draft-internal-glossary.markdown b/docs/internal/draft-internal-glossary.markdown deleted file mode 100644 index bafc9364f9d..00000000000 --- a/docs/internal/draft-internal-glossary.markdown +++ /dev/null @@ -1,130 +0,0 @@ -# Glossary - -## Path types - -### Absolute path - -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. - -### Relative path - -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. - -## Path sources - -Now that the path types are defined, let's set up some examples for the rest of this document. - -### Project roots - -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`. - - -## Directories - -### Project directory - -The project directory is the directory that contains all the project files. This is the same as the project root. - -### Source directories - -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 - -### (Site) Output directory - -The output directory is the directory that Hyde will output the generated site to. By default, this is the `_site` directory. - -### Nested directories - -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. - - -## URL components - -HydePHP follows the [MDN description of URLs](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL) which can be visualized using their graphic (CC-BY-SA): -![URL components](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL/mdn-url-all.png) - - -### Paths VS links - -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. - -### Just links - -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, - -### Relative links - -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 - -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 links - -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/URLs - -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 `/`. - -## Path components and terminologies - -Now that we have the basics out of the way, let's get into the specifics AKA the more interesting stuff. - - -### Identifiers - -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). - -### Route keys - -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). - -### Variable naming conventions - -* `$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` - -### Visualizing the anatomy of a file name - -Text in [brackets] show data that is implied by the context, but are not a part of the value itself. - -#### Identifier (Slug) -[_posts/]**hello-world**[.md] - -#### File Name -[_posts/]**hello-world.md** - -#### File Path -**_posts/hello-world.md** - -#### Route Key -**posts/hello-world** - -#### Output Path -[_site/]**posts/hello-world.html** From 6b3da8959a40f48e747955796a6e1b0bb1706350 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 13 Mar 2023 19:00:25 +0100 Subject: [PATCH 2/4] Delete draft-developer-definitions.markdown --- .../draft-developer-definitions.markdown | 30 ------------------- 1 file changed, 30 deletions(-) delete mode 100644 docs/internal/draft-developer-definitions.markdown diff --git a/docs/internal/draft-developer-definitions.markdown b/docs/internal/draft-developer-definitions.markdown deleted file mode 100644 index 71f069d34f7..00000000000 --- a/docs/internal/draft-developer-definitions.markdown +++ /dev/null @@ -1,30 +0,0 @@ -# Internal code definitions and naming conventions for framework developers - -In an attempt to reduce redundant PHPDoc comments within the internal code I thought it could be useful to write definitions for the various terms I have been using. - -If you have ideas for improvement, additions, clarifications, or anything else, please raise an issue on the [DocsCI Repo](https://github.com/hydephp/DocsCI)! - -## Common variable names and their meaning -**$matter**: YAML Front Matter, usually parsed into an array. -**$body**: The main content of a document, usually in the form of unparsed Markdown -**$title**: The string used to set the HTML title in compiled pages. -**$slug**: The basename of a file. See the chapter "Anatomy of a File Name" for more. A slug never has a file extension and does not contain any path information (prefixes). (internally also known as `identifier`). -Example: `hello-world` -**$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` - -## Deep dives - -### Anatomy of a File Name -Hyde makes frequent references to file names. Here are some visualizations of the different parts of a file name. - -#### Slug (Basename/Identifier) -_posts/**hello-world**.md - -#### File Name -_posts/**hello-world.md** - -#### File Path -**_posts/hello-world.md** From 52901a5fe15362878deb9e286fc9b492919ab5ef Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 11 Mar 2023 19:52:45 +0100 Subject: [PATCH 3/4] Create .gitignore --- monorepo/scripts/cache/.gitignore | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 monorepo/scripts/cache/.gitignore diff --git a/monorepo/scripts/cache/.gitignore b/monorepo/scripts/cache/.gitignore new file mode 100644 index 00000000000..d6b7ef32c84 --- /dev/null +++ b/monorepo/scripts/cache/.gitignore @@ -0,0 +1,2 @@ +* +!.gitignore From 556eb82e5c0bf337e9bc38d2ef0235b7bd21f77c Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 8 Mar 2023 15:02:02 +0100 Subject: [PATCH 4/4] Update .editorconfig --- .editorconfig | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.editorconfig b/.editorconfig index 94eee1d71bd..a34fc0fe258 100644 --- a/.editorconfig +++ b/.editorconfig @@ -749,7 +749,7 @@ ij_json_wrap_long_lines = false ij_html_add_new_line_before_tags = body,div,p,form,h1,h2,h3 ij_html_align_attributes = true ij_html_align_text = false -ij_html_attribute_wrap = normal +ij_html_attribute_wrap = off ij_html_block_comment_add_space = false ij_html_block_comment_at_first_column = true ij_html_do_not_align_children_of_min_lines = 0 @@ -771,7 +771,7 @@ ij_html_remove_new_line_before_tags = br ij_html_space_after_tag_name = false ij_html_space_around_equality_in_attribute = false ij_html_space_inside_empty_tag = false -ij_html_text_wrap = normal +ij_html_text_wrap = off [{*.http,*.rest}] indent_size = 0