From 14cf9d5e2181fadfae7f6c7a64f0a49f55760624 Mon Sep 17 00:00:00 2001 From: Thomas Lange Date: Tue, 20 Jul 2021 18:37:14 +0200 Subject: Update documentation for content functions --- Editor.md | 113 ++++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 80 insertions(+), 33 deletions(-) (limited to 'Editor.md') diff --git a/Editor.md b/Editor.md index 3659d7f..8d776f9 100644 --- a/Editor.md +++ b/Editor.md @@ -1,36 +1,83 @@ -If you wanna link an item of your blog application, please don't put the absolute URL hardcoded into the content editor. What if you want to change your blogs address (or just the base directory) in the future? You would have to change all the hardcoded links in your content. This is not cool! Therefore, you can use the following special syntax within the content editor to link any resource of your installation dynamically. - -**Note:** You can combine these codes with markdown syntax because the special codes are processed before the markdown parser walks through the content. The markdown parser will never see the original syntax of this special codes, but rather the result (an absolute URL) of those. - -## Dynamic linking of resources -You can link resources which are located anywhere within your installation dynamically, either relative to your base directory or relative to your `rsrc` directory where you store your files like images and other stuff (this is the preferred method to include an image within your items content): - -* Write `{BASE["other/directory/"]}` into the editor and get: -`https://hostname/other/directory/` -* Write `{FILE["image/foobar.jpg"]}` into the editor and get: -`https://hostname/rsrc/image/foobar.jpg` - -### Combined with markdown syntax for displaying images -* Write `![A foobar image]({FILE["image/foobar.jpg"]})` into the editor and get: -`A foobar image` - -## Dynamic linking of pages, posts and users -You have to know the unique ID of the item which you can find in the administration area, so that the system can identify it and replace the code with the items URL (if you put an ID into the syntax which does not exist, the output in your HTML will be just `{undefined}`): - -* Write `{PAGE[123]}` into the editor and get: -`https://hostname/page/page-with-id-123/` -* Write `{POST[123]}` into the editor and get: -`https://hostname/post/post-with-id-123/` -* Write `{USER[123]}` into the editor and get: -`https://hostname/user/user-with-id-123/` - -### Combined with markdown syntax for URL linking: -* Write `[A cool page]({PAGE[123]})` into the editor and get: -`A cool page` -* Write `[A cool post]({POST[123]})` into the editor and get: -`A cool post` -* Write `[A cool user]({USER[123]})` into the editor and get: -`A cool user` +If you want to reference another item (e.g. a post or a category) in your content, please do not put the URL to it hardcoded into the editor. Consider what happens if you change your blog's address (or just the base directory) in the future. You would need to change all the hardcoded URLs in your content which is inflexible and not cool. Therefore, you can use the following so-called [*content functions*](Content_Functions) to link an item or a resource of your installation dynamically within your Markdown content. + +**Note:** You can combine these functions with Markdown syntax since they are processed and transformed before the Markdown parser finally transforms the content to HTML. There is even the possibility [to add your own custom functions](Content_Functions#how-to-add-custom-functions). + +## Relative URLs +You can link any resource (e.g. a file) which is located anywhere within your document root dynamically, either relative to your base directory (the installation directory) or relative to the `rsrc` directory where you store your files, images and other stuff. The `BASE_URL` and `FILE_URL` functions will return the pure plain text URL (extended by the first argument). + +### Example #1 +~~~markdown +Hello there. Check out [the README]({BASE_URL: "readme.md"})! +~~~ +~~~markdown + +Hello there. Check out [the README](https://blog.git/readme.md)! +~~~ +~~~html + +Hello there. Check out the README! +~~~ + +### Example #2 +~~~markdown +![A cute kitten]({FILE_URL: "image/content/kitten.jpg"} "Look at this!") +~~~ +~~~markdown + +![A cute kitten](https://blog.git/rsrc/image/content/kitten.jpg "Look at this!") +~~~ +~~~html + +A cute kitten +~~~ + +## Linking items in your content (categories, pages, posts and users) +The following examples show you how to link a post in the content editor from any other item. + +Instead of returing just the pure URL like the `BASE_URL` or `FILE_URL` functions do, the item functions returning the complete Markdown formatted hyperlink syntax (including the text for the `title` attribute). + +The first argument is expected to be the unique ID of the item (which you can find in the administration area). If the second argument is present, it will be used as the hyperlink text; if it is omitted, the post title will be used as the hyperlink text. The third and last argument, if present, is used to customize the text for the `title` attribute of the final HTML's `` tag. + +### Example #1 +~~~markdown +Hello there! Check out this post: {POST: 1} +~~~ +~~~markdown + +Hello there! Check out this post: [»Hello World!«](https://blog.git/post/hello-world/ "Post »Hello World!«") +~~~ +~~~html + +Hello there! Check out this post: »Hello World!« +~~~ + +### Example #2 +~~~markdown +Hello there! Check out {POST: 1, "this post"}! +~~~ +~~~markdown + +Hello there! Check out [this post](https://blog.git/post/hello-world/ "Post »Hello World!«")! +~~~ +~~~html + +Hello there! Check out this post! +~~~ + +### Example #3 +~~~markdown +Hello there! Check out {POST: 1, "this post", "Click to show post"}! +~~~ +~~~markdown + +Hello there! Check out [this post](https://blog.git/post/hello-world/ "Click to show post")! +~~~ +~~~html + +Hello there! Check out this post! +~~~ + +**Note:** The same syntax can also be used for the `CATEGORY`, `PAGE` and `USER` functions! -- cgit v1.2.3