Skip to content
This repository was archived by the owner on Jun 18, 2022. It is now read-only.

Commit 9ac747b

Browse files
caendesilvacaendesilva
authored
Merge pull request #18 from hydephp/rewrite-docs
Rewrite docs
2 parents 0f90b50 + 14ccdc9 commit 9ac747b

16 files changed

+1180
-513
lines changed

‎_drafts/how-does-it-work.md

-13
This file was deleted.

‎architecture-concepts.md

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
priority: 5
3+
category: "Getting Started"
4+
---
5+
6+
# Some key concepts in Hyde
7+
8+
## The HydeCLI
9+
10+
When you are not writing Markdown and Blade, most of your interactions with Hyde will be through the
11+
Hyde Command Line Interface (CLI).
12+
Since the CLI is based on the Laravel Artisan Console, so you may actually already be familiar with it.
13+
14+
You should take a look at [the Console Commands page](console-commands.html)
15+
to learn more and see the available commands and their usage.
16+
17+
```bash
18+
php hyde <command> [--help]
19+
```
20+
21+
## Directory structure
22+
23+
To take full advantage of the framework, it may first be good to familiarize ourselves with the directory structure.
24+
25+
```
26+
// torchlight! {"lineNumbers": false}
27+
├── _docs // For documentation pages
28+
├── _posts // For blog posts
29+
├── _pages // For static Markdown and Blade pages
30+
├── _media // Store static assets to be copied to the build directory
31+
├── _site // The build directory where your compiled site will be stored
32+
├── config // Configuration files for Hyde and integrations
33+
├── resources/assets // Location for Laravel Mix source files (optional)
34+
└── resources/views/components // Location for Blade components (optional)
35+
```
36+
37+
> Note that the `_site` directory is emptied every time you run the `hyde build` command.
38+
> It's intended that you keep the directory out of your VCS, for example by adding it to your .gitignore file.
39+
40+
41+
## File Autodiscovery
42+
43+
Content files, meaning source Markdown and Blade files, are automatically
44+
discovered by Hyde and compiled to HTML when building the site.
45+
This means that you don't need to worry about routing and controllers!
46+
47+
The directory a source file is in will determine the Blade template that is used to render it.
48+
49+
Here is an overview of the content source directories, the output directory of the compiled files,
50+
and the file extensions supported by each. Files starting with an `_underscore` are ignored.
51+
52+
| Page/File Type | Source Directory | Output Directory | File Extensions |
53+
|----------------|------------------|------------------|---------------------|
54+
| Static Pages | `_pages/` | `_site/` | `.md`, `.blade.php` |
55+
| Blog Posts | `_posts/` | `_site/posts/` | `.md` |
56+
| Documentation | `_docs/` | `_site/docs/` | `.md` |
57+
| Media Assets | `_media/` | `_site/media/` | See full list below |
58+
59+
<small>
60+
<blockquote>
61+
Media file types supported: `.png`, `.svg`, `.jpg`, `.jpeg`, `.gif`, `.ico`, `.css`, `.js`
62+
</blockquote>
63+
</small>
64+
65+
## Convention over Configuration
66+
67+
Hyde favours the "Convention over Configuration" paradigm and thus comes preconfigured with sensible defaults.
68+
However, Hyde also strives to be modular and endlessly customizable hackable if you need it.
69+
Take a look at the [customization and configuration guide](customization.html) to see the endless options available!
70+
71+
## Front Matter
72+
73+
All Markdown content files support Front Matter. Blog posts for example make heavy use of it.
74+
75+
The specific usage and schemas used for pages are documented in their respective documentation,
76+
however, here is a primer on the fundamentals.
77+
78+
- Front matter is stored in a block of YAML that starts and ends with a `---` line.
79+
- The front matter should be the very first thing in the Markdown file.
80+
- Each key-pair value should be on its own line.
81+
82+
**Example:**
83+
```markdown
84+
---
85+
title: "My New Post"
86+
author:
87+
name: "John Doe"
88+
website: https://mrhyde.example.com
89+
---
90+
91+
## Markdown comes here
92+
93+
Lorem ipsum dolor sit amet, etc.
94+
```

‎blog-posts.md

+221
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
---
2+
label: "Creating Blog Posts"
3+
priority: 10
4+
category: "Creating Content"
5+
---
6+
7+
# Creating Blog Posts
8+
9+
## Introduction to Hyde Posts
10+
11+
Making blog posts with Hyde is easy. At the most basic level,
12+
all you need is to add a Markdown file to your `_posts` folder.
13+
14+
To use the full power of the Hyde post module however,
15+
you'll want to add YAML Front Matter to your posts.
16+
17+
You can scaffold posts with automatic front matter using the HydeCLI:
18+
```bash
19+
php hyde make:post
20+
```
21+
Learn more about scaffolding posts, and other files, in the [console commands](console-commands.html) documentation.
22+
23+
24+
## Short Video Tutorial
25+
26+
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/gjpE1U527h8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
27+
28+
## Best Practices and Hyde Expectations
29+
30+
Since Hyde does a lot of things automatically, there are some things you may need
31+
to keep in mind when creating blog posts so that you don't get unexpected results.
32+
33+
### Filenames
34+
35+
- Markdown post files are stored in the `_posts` directory
36+
- The filename is used as the filename for the compiled HTML
37+
- Filenames should use `kebab-case-slug` followed by the extension `.md`
38+
- Files prefixed with `_underscores` are ignored by Hyde
39+
- Your post will be stored in `_site/posts/<slug>.html`
40+
41+
**Example:**
42+
```bash
43+
✔ _posts/hello-world.md # Valid and will be compiled to _site/posts/hello-world.html
44+
```
45+
46+
### Front Matter
47+
48+
Front matter is optional, but highly recommended for blog posts.
49+
50+
You can read more about the Front Matter format in the [Front Matter documentation](architecture-concepts.html#front-matter).
51+
Here is a quick primer:
52+
53+
- Front matter is stored in a block of YAML that starts and ends with a `---` line.
54+
- The front matter should be the very first thing in the Markdown file.
55+
- Each key-pair value should be on its own line.
56+
- The front matter is used to construct dynamic HTML markup for the post as well as meta tags and post feeds.
57+
You are encouraged to look at the compiled HTML to learn and understand how your front matter is used.
58+
59+
60+
**Example:**
61+
```markdown
62+
---
63+
title: "My New Post"
64+
---
65+
66+
## Markdown comes here
67+
```
68+
69+
You can use the `php hyde make:post` command to automatically generate the front matter based on your input.
70+
71+
72+
## A first look at Front Matter
73+
74+
Before digging in deeper on all the supported front matter options,
75+
let's take a look at what a basic post with front matter looks like.
76+
77+
This file was created using the `make:post` by hitting the `Enter` key to use
78+
all the defaults (with some extra lorem ipsum to illustrate).
79+
80+
```markdown {: filepath="_posts/my-new-post.md"}
81+
---
82+
title: My New Post
83+
description: A short description used in previews and SEO
84+
category: blog
85+
author: Mr. Hyde
86+
date: 2022-05-09 18:38
87+
---
88+
89+
## Write your Markdown here
90+
91+
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
92+
Autem aliquid alias explicabo consequatur similique,
93+
animi distinctio earum ducimus minus, magnam.
94+
```
95+
96+
### How the Front Matter is used
97+
98+
The front matter is used to construct dynamic HTML markup for the post as well as meta tags and post feeds.
99+
100+
You are encouraged to look at the compiled HTML to learn and understand how your front matter is used.
101+
102+
### Front matter syntax
103+
104+
Here is a quick reference of the syntax Hyde uses and expects:
105+
106+
```markdown
107+
---
108+
key: value
109+
string: "quoted string"
110+
boolean: true
111+
integer: 100
112+
array:
113+
key: value
114+
key: value
115+
---
116+
```
117+
118+
## Supported Front Matter properties
119+
120+
### Post Front Matter Schema
121+
122+
Here is a quick reference of the supported front matter properties.
123+
Keep on reading to see further explanations, details, and examples.
124+
125+
126+
| **KEY NAME** | **VALUE TYPE** | **EXAMPLE / FORMAT** |
127+
|----------------|----------------|----------------------------------|
128+
| `title` | string | "My New Post" |
129+
| `description` | string | "A short description" |
130+
| `category` | string | "my favorite recipes" |
131+
| `date` | string | "YYYY-MM-DD [HH:MM]" |
132+
| `author` | string/array | _See [author](#author) section_ |
133+
| `image` | string/array | _See [image](#image) section_ |
134+
135+
136+
Note that YAML here is pretty forgiving. In most cases you do not need to wrap strings
137+
in quotes, but it can help in certain edge cases, thus they are included here.
138+
139+
In the examples below, when there are multiple keys, they signify various ways to use the parameter.
140+
141+
### Title
142+
143+
```yaml
144+
title: "My New Post"
145+
```
146+
147+
148+
### Description
149+
150+
```yaml
151+
description: "A short description used in previews and SEO"
152+
```
153+
154+
155+
### Category
156+
157+
```yaml
158+
category: blog
159+
category: "My favorite recipes"
160+
```
161+
162+
163+
### Date
164+
165+
```yaml
166+
date: "2022-01-01 12:00"
167+
date: "2022-01-01"
168+
```
169+
170+
171+
### Author
172+
173+
```yaml
174+
author: "Mr. Hyde" # Arbitrary name displayed "as is"
175+
author: mr_hyde # Username defined in `authors.yml` config
176+
author: # Array of author data
177+
name: "Mr. Hyde"
178+
username: mr_hyde
179+
website: https://mrhyde.example.com
180+
```
181+
182+
When specifying an array you don't need all the sub-properties.
183+
The example just shows all the supported values. Array values here
184+
will override the values in the `authors.yml` config.
185+
186+
### Image
187+
188+
```yaml
189+
image: image.jpg # Expanded by Hyde to `_media/image.jpg` and is resolved automatically
190+
image: https://cdn.example.com/image.jpg # Full URL starting with `http(s)://`)
191+
image:
192+
path: image.jpg
193+
uri: https://cdn.example.com/image.jpg # Takes precedence over `path`
194+
description: "Alt text for image"
195+
title: "Tooltip title"
196+
copyright: "Copyright (c) 2022"
197+
license: "CC-BY-SA-4.0"
198+
licenseUrl: https://example.com/license/
199+
credit: https://photographer.example.com/
200+
author: "John Doe"
201+
```
202+
203+
When supplying an image with a local image path, the image is expected to be stored in the `_media/` directory.
204+
205+
The image will be used as the cover image, and any array data is constructed into a dynamic fluent caption,
206+
and injected into post and page metadata.
207+
208+
> See [posts/introducing-images](https://hydephp.github.io/posts/introducing-images.html)
209+
> for a detailed blog post with examples and schema information!
210+
{ .info }
211+
212+
213+
## Using images in posts
214+
215+
To use images stored in the `_media/` directory, you can use the following syntax:
216+
217+
```markdown
218+
![Image Alt](../media/image.png "Image Title") # Note the relative path
219+
```
220+
221+
To learn more, check out the [chapter in managing assets](managing-assets.html#managing-images)

0 commit comments

Comments
 (0)