From 58c68ee055ea8befc051ee999e67188009aab63f Mon Sep 17 00:00:00 2001 From: satnaing Date: Sun, 24 Sep 2023 22:46:46 +0630 Subject: [PATCH] docs: update docs for astro-papaer v3 Make docs articles up to date with the latest version of AstroPaper. Add a section for storing images for blog posts. Rename rec-2 to example-draft-post and update its content. resolve #117 --- src/content/blog/adding-new-post.md | 61 ++++++++++++++++--- src/content/blog/dynamic-og-images.md | 1 - .../blog/{rec-2.md => example-draft-post.md} | 6 +- 3 files changed, 55 insertions(+), 13 deletions(-) rename src/content/blog/{rec-2.md => example-draft-post.md} (68%) diff --git a/src/content/blog/adding-new-post.md b/src/content/blog/adding-new-post.md index 35528cc..f46c2f8 100644 --- a/src/content/blog/adding-new-post.md +++ b/src/content/blog/adding-new-post.md @@ -18,7 +18,7 @@ Here are some rules/recommendations, tips & ticks for creating new posts in Astr ## Frontmatter -Frontmatter is the main place to store some important information about the post (article). Frontmatter lies at the top of the article and is written in YAML format. Read more about frontmatter and its usage in [astro documentation](https://docs.astro.build/en/guides/markdown-content/). +Frontmatter is the main place to store some important information about the blog post (article). Frontmatter lies at the top of the article and is written in YAML format. Read more about frontmatter and its usage in [astro documentation](https://docs.astro.build/en/guides/markdown-content/). Here is the list of frontmatter property for each post. @@ -41,16 +41,15 @@ Title and description (excerpt) are important for search engine optimization (SE `slug` is the unique identifier of the url. Thus, `slug` must be unique and different from other posts. The whitespace of `slug` needs to be separated with `-` or `_` but `-` is recommended. However, even if you don't write the correct slug, AstroPaper will automatically slugify your incorrect slug. If slug is not specified, the slugified title of the post will be used as slug. -If you omit `tags` in a blog post (in other words, if no tag is specified), the default tag `others` will be used as a tag for that post. You can set the default tag in the `/src/content/_schemas.ts` file. +If you omit `tags` in a blog post (in other words, if no tag is specified), the default tag `others` will be used as a tag for that post. You can set the default tag in the `/src/content/config.ts` file. ```ts -// src/contents/_schemas.ts +// src/content/config.ts export const blogSchema = z.object({ // --- - // replace "others" with whatever you want - tags: z.array(z.string()).default(["others"]), - ogImage: z.string().optional(), - description: z.string(), + draft: z.boolean().optional(), + tags: z.array(z.string()).default(["others"]), // replace "others" with whatever you want + // --- }); ``` @@ -59,7 +58,7 @@ export const blogSchema = z.object({ Here is the sample frontmatter for a post. ```yaml -# src/contents/sample-post.md +# src/content/blog/sample-post.md --- title: The title of the post author: your name @@ -103,11 +102,55 @@ There's one thing to note about headings. The AstroPaper blog posts use title (t This rule is not mandatory, but highly recommended for visual, accessibility and SEO purposes. +## Storing Images for Blog Content + +Here are two methods for storing images and displaying them inside a markdown file. + +> Note! If it's a requirement to style optimized images in markdown you should [use MDX](https://docs.astro.build/en/guides/images/#images-in-mdx-files). + +### Inside `src/assets/` directory (recommended) + +You can store images inside `src/assets/` directory. These images will be automatically optimized by Astro through [Image Service API](https://docs.astro.build/en/reference/image-service-reference/). + +You can use relative path or alias path (`@assets/`) to serve these images. + +Example: Suppose you want to display `example.jpg` whose path is `/src/assets/images/example.jpg`. + +```md +![something](@assets/images/example.jpg) + + + +![something](../../assets/images/example.jpg) + + +something + +``` + +> Technically, you can store images inside any directory under `src`. In here, `src/assets` is just a recommendation. + +### Inside `public` directory + +You can store images inside the `public` directory. Keep in mind that images stored in the `public` directory remain untouched by Astro, meaning they will be unoptimized and you need to handle image optimization by yourself. + +For these images, you should use an absolute path; and these images can be displayed using [markdown annotation](https://www.markdownguide.org/basic-syntax/#images-1) or [HTML img tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img). + +Example: Assume `example.jpg` is located at `/public/assets/images/example.jpg`. + +```md +![something](/assets/images/example.jpg) + + + +something +``` + ## Bonus ### Image compression -When you put images in the blog post, it is recommended that the image is compressed. This will affect the overall performance of the website. +When you put images in the blog post (especially for images under `public` directory), it is recommended that the image is compressed. This will affect the overall performance of the website. My recommendation for image compression sites. diff --git a/src/content/blog/dynamic-og-images.md b/src/content/blog/dynamic-og-images.md index 4173c72..f8984a9 100644 --- a/src/content/blog/dynamic-og-images.md +++ b/src/content/blog/dynamic-og-images.md @@ -48,4 +48,3 @@ At the time of writing this, [Satori](https://github.com/vercel/satori) is fairl - If you have Blog posts with non-English titles, you have to set `embedFonts` option to `false` (file: `src/utils/generateOgImage.tsx`). Even after this, the OG image might not be displayed very well. - Besides, RTL languages are not supported yet. - [Using emoji](https://github.com/vercel/satori#emojis) in the title might be a little bit tricky. -- Sadly, this new dynamic OG image generation feature cannot be used for Twitter social images since `svg` image type is not supported for Twitter Cards. diff --git a/src/content/blog/rec-2.md b/src/content/blog/example-draft-post.md similarity index 68% rename from src/content/blog/rec-2.md rename to src/content/blog/example-draft-post.md index b20bbf9..446ba95 100644 --- a/src/content/blog/rec-2.md +++ b/src/content/blog/example-draft-post.md @@ -1,8 +1,8 @@ --- -title: My recent article 2 +title: Example Draft Post author: Sat Naing pubDatetime: 2022-06-06T04:06:31Z -postSlug: my-recent-2 +postSlug: example-draft-post featured: false draft: true tags: @@ -14,7 +14,7 @@ description: fringilla est --- -My experience about developing my first portfolio website and a blog using NextJS and a headless CMS. +Users cannot see this post because it is in draft. ## Motivation