From 3db96904dc5d5dd9659bd43098a35a6079ca5606 Mon Sep 17 00:00:00 2001 From: Bekah Hawrot Weigel Date: Tue, 4 Jun 2024 11:02:27 -0400 Subject: [PATCH 1/6] Add blog guide for posting to our community resources --- .../how-to-add-your-post.md | 98 +++++++++++++++++++ sidebars.js | 8 ++ 2 files changed, 106 insertions(+) create mode 100644 docs/contributing/opensauced-writers-guide/how-to-add-your-post.md diff --git a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md new file mode 100644 index 00000000..410b4111 --- /dev/null +++ b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md @@ -0,0 +1,98 @@ +--- +id: writers-guide +title: "OpenSauced Writers Guide" +sidebar_label: "OpenSauced Writers Guide" +keywords: +- "writers guide" +- "open source writers guide" +- "open source writer" +--- + +Welcome to our Writers Contributor Guide. This will walk you through the steps of how to add your blog post to our community resources using the docs repository. + +## Repeat Authors: Adding to `authors.yml` + +For regular blog post authors, we should declare those authors globally in the configuration file: + +**Location:** `/blog/authors.yml` + +**Example:** +```yaml +BekahHW: + name: Bekah Hawrot Weigel + title: Developer Experience Lead + url: https://twitter.com/BekahHW + image_url: https://github.com/BekahHW.png + email: Bekah@opensauced.pizza + twitter: BekahHW + +nickytonline: + name: Nick Taylor + title: AI Engingeer + url: https://www.nickyt.co/ + image_url: https://github.com/nickytonline.png +``` + +## Adding Blog Posts + +To publish in the blog, create a Markdown file within the blog directory. Note that we have subdirectories for each year, so writers should add their post to the folder that corresponds with the year. + +**Example Path:** `/blog/2024/06-03-welcome-opensauced.md` + + +:::info + +You'll notice that many of the files include the year. These were created before we started using the year subdirectories. Either way works, but we're moving towards the year subdirectories for organization and omitting the year in the file name. + +::: + +**Markdown Example:** +```markdown +docs/blog/2024/06-03-welcome-opensauced.md +--- +title: Welcome to OpenSauced +description: This is my first post on OpenSauced. +slug: welcome-opensauced +authors: BekahHW +tags: [hello, opensauced] +hide_table_of_contents: false +--- + +Welcome to this blog. This blog is created with [**OpenSauced**](https://opensauced.pizza). + + + +This is my first post on OpenSauced. + +A whole bunch of exploration to follow. +``` + +The front matter is useful to add more metadata to your blog post, for example, author information, but OpenSauced will be able to infer all necessary metadata without the front matter. For all possible fields, see the API documentation. + +### Blog List + +The blog's index page (a custom path for OpenSauced at `/community-resources`) is the blog list page, where all blog posts are collectively displayed. + +Use the `` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `` will be part of the summary. Note that the portion above the truncate marker must be standalone renderable Markdown. For example: + +**Example Path:** `website/blog/my-post.md` + +**Markdown Example:** +```markdown +website/blog/my-post.md +--- +title: Markdown blog truncation example +--- + +All these will be part of the blog post summary. + + + +But anything from here on down will not be. +``` + +### Image Usage + +We are not going to use images in the front matter. The rest of the post should be in markdown format. + +By following these guidelines, you will ensure consistency and ease of maintenance across our blog posts. Happy writing! \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index aeb0b0f5..0d0b47b3 100644 --- a/sidebars.js +++ b/sidebars.js @@ -158,6 +158,14 @@ module.exports = { collapsed: true, items: ["contributing/technical/setup-repo-with-git", "contributing/technical/resolve-merge-conflicts"], }, + { + type: "category", + label: "OpenSauced Writers Guides", + collapsed: true, + items: [ + "contributing/opensauced-writers-guide/writers-guide", + ], + }, ], }, { From 86aff54abc0cde382e3d1e829a888180232f4e0f Mon Sep 17 00:00:00 2001 From: BekahHW <34313413+BekahHW@users.noreply.github.com> Date: Wed, 5 Jun 2024 10:58:24 -0400 Subject: [PATCH 2/6] Update docs/contributing/opensauced-writers-guide/how-to-add-your-post.md Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com> --- .../opensauced-writers-guide/how-to-add-your-post.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md index 410b4111..09b1a8c2 100644 --- a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md +++ b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md @@ -28,7 +28,7 @@ BekahHW: nickytonline: name: Nick Taylor - title: AI Engingeer + title: AI Engineer url: https://www.nickyt.co/ image_url: https://github.com/nickytonline.png ``` From ef40a0bbf9ce7b1cd9e3b041f2157f5c20734402 Mon Sep 17 00:00:00 2001 From: Bekah Hawrot Weigel Date: Wed, 5 Jun 2024 11:13:33 -0400 Subject: [PATCH 3/6] Clarify authors.yml --- .../opensauced-writers-guide/how-to-add-your-post.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md index 09b1a8c2..381ef7d4 100644 --- a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md +++ b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md @@ -12,7 +12,7 @@ Welcome to our Writers Contributor Guide. This will walk you through the steps o ## Repeat Authors: Adding to `authors.yml` -For regular blog post authors, we should declare those authors globally in the configuration file: +For regular blog post authors, we should declare those authors globally in the configuration file. Below is an example of how to add an author to the `authors.yml` file: **Location:** `/blog/authors.yml` @@ -33,6 +33,13 @@ nickytonline: image_url: https://github.com/nickytonline.png ``` +### Tips + +All authors should include their name and an image URL. The title, URL, and email are optional fields. We do not recommend using your personal email. If you don't currently have a job title, feel free to use a volunteer title or a title that best describes your role in the community. For instance, you could write, "OpenSauced Community Writer." + +If you do want to include a URL, you can include your OpenSauced profile, X, LinkedIn, personal website, etc. + + ## Adding Blog Posts To publish in the blog, create a Markdown file within the blog directory. Note that we have subdirectories for each year, so writers should add their post to the folder that corresponds with the year. From 80bd2766a59e26c1e2634cd60bc039d567a13d0b Mon Sep 17 00:00:00 2001 From: Bekah Hawrot Weigel Date: Wed, 5 Jun 2024 11:18:40 -0400 Subject: [PATCH 4/6] Add more clarity to description --- .../how-to-add-your-post.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md index 381ef7d4..14486725 100644 --- a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md +++ b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md @@ -74,7 +74,22 @@ This is my first post on OpenSauced. A whole bunch of exploration to follow. ``` -The front matter is useful to add more metadata to your blog post, for example, author information, but OpenSauced will be able to infer all necessary metadata without the front matter. For all possible fields, see the API documentation. +### Front Matter + +The front matter is the metadata at the top of the Markdown file. It includes the title, description, slug, authors, tags, and hide_table_of_contents. + +- **title:** The title of the blog post. +- **description:** A brief description of the blog post. +- **slug:** The slug is the URL-friendly version of the title. It should be lowercase and hyphenated. +- **authors:** The author of the blog post. If there are multiple authors that appear in the authors.yml, this is what it should look like: + +```markdown +--- +authors:[BekahHW, nickytonline] +--- +``` +- **tags:** Tags are used to categorize the blog post. They should be lowercase and separated by commas and highlight the main topics of the blog post. +- **hide_table_of_contents:** This is a boolean value that determines whether the table of contents will be displayed. If you want to hide the table of contents, set it to `true`. ### Blog List From dae7225a93e7cb2c1873d0ccf214cb065b133b1e Mon Sep 17 00:00:00 2001 From: Bekah Hawrot Weigel Date: Wed, 5 Jun 2024 11:21:16 -0400 Subject: [PATCH 5/6] Clarify images --- .../opensauced-writers-guide/how-to-add-your-post.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md index 14486725..fcdf069f 100644 --- a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md +++ b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md @@ -95,9 +95,7 @@ authors:[BekahHW, nickytonline] The blog's index page (a custom path for OpenSauced at `/community-resources`) is the blog list page, where all blog posts are collectively displayed. -Use the `` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `` will be part of the summary. Note that the portion above the truncate marker must be standalone renderable Markdown. For example: - -**Example Path:** `website/blog/my-post.md` +Use the `` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `` will be part of the summary. Note that the portion above the truncate marker must be standalone renderable Markdown. **Markdown Example:** ```markdown @@ -117,4 +115,6 @@ But anything from here on down will not be. We are not going to use images in the front matter. The rest of the post should be in markdown format. +If you want to include images within your post, please use only images that directly relate to the content of the post. If you need to add an image to the repository (rather than linking from somewhere else), you can add it to the `/static` directory in the `gif` or `img` subdirectory. + By following these guidelines, you will ensure consistency and ease of maintenance across our blog posts. Happy writing! \ No newline at end of file From d91bb13a197c71714deceb9a8052187fc0cb7c8f Mon Sep 17 00:00:00 2001 From: BekahHW <34313413+BekahHW@users.noreply.github.com> Date: Wed, 5 Jun 2024 14:13:34 -0400 Subject: [PATCH 6/6] Update docs/contributing/opensauced-writers-guide/how-to-add-your-post.md Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> --- .../opensauced-writers-guide/how-to-add-your-post.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md index fcdf069f..6bafeb82 100644 --- a/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md +++ b/docs/contributing/opensauced-writers-guide/how-to-add-your-post.md @@ -42,7 +42,7 @@ If you do want to include a URL, you can include your OpenSauced profile, X, Lin ## Adding Blog Posts -To publish in the blog, create a Markdown file within the blog directory. Note that we have subdirectories for each year, so writers should add their post to the folder that corresponds with the year. +To publish in the blog, create a Markdown file within the blog directory. Note that we have subdirectories for each year, so writers should add their posts to the folder that corresponds with the year. **Example Path:** `/blog/2024/06-03-welcome-opensauced.md`