From 39c2129d692e7132152058f1c7be417b7ec6b578 Mon Sep 17 00:00:00 2001 From: Ildiko Vancsa Date: Wed, 3 Nov 2021 17:49:12 -0700 Subject: [PATCH] Add docs about contributing a blog post This patch adds a brief description about contributing a new blog post to the StarlingX website. Change-Id: Ifec9958fa3d87bf6e29d4b1e6f0d6b107541eacc Signed-off-by: Ildiko Vancsa --- .../contributor/blog_contribute_guide.rst | 112 ++++++++++++++++++ doc/source/contributor/index.rst | 3 +- 2 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 doc/source/contributor/blog_contribute_guide.rst diff --git a/doc/source/contributor/blog_contribute_guide.rst b/doc/source/contributor/blog_contribute_guide.rst new file mode 100644 index 000000000..1351a6bc2 --- /dev/null +++ b/doc/source/contributor/blog_contribute_guide.rst @@ -0,0 +1,112 @@ +.. _blog_contribute_guide: + +=========================== +Blog Post Contributor Guide +=========================== + +This section describes the guidelines for contributing new blog posts to the +StarlingX website. + +.. contents:: + :local: + :depth: 1 + +------------------------------------------- +Share your stories on the StarlingX Website +------------------------------------------- + +Are you experimenting with StarlingX or have it deployed in production and +would like to share your story as a case study? Do you have an edge use case +that StarlingX fits into, but the world doesn't know it yet? Do you have +features in the platform that you like and would like to highlight? Do you have +a StarlingX demo that you would like to draw attention to? + +Share your StarlingX story on the `StarlingX blog +`_! You are only a few steps away... + +************************ +StarlingX website source +************************ + +Unlike the rest of the StarlingX artifacts, the StarlingX website code and +content is stored in a `GitHub repository +`_. + +The blog posts are written using markdown language that is mainly plain text with a few +easy formatting conventions to create lists, add images or code blocks, or +format the text. + +You can find many `cheat sheets `_ +floating on the web to get in terms of the basic syntax. You can also check the +`source files of the already existing blog posts +`_ +, where you will find examples of all the basic items that you will +need for your new entry. + +********************** +Create a new blog post +********************** + +When you create a new blog post, you need to create a new file in the +`'src/pages/blog/' folder +`_ +with a '.md' extension. + +Files are usually named 'starlingx-.md'. + +The markdown file has a few formatting conventions in its header to capture the +title, author, publishing date and category of your blog post. + +The header looks like the following: + +:: + + --- + templateKey: blog-post + title: The Title of Your Amazing Blog Post + author: Your Name + date: 2021-01-28T16:23:52.741Z + category: + - label: News & Announcements + id: category-A7fnZYrE1 + --- + +The categories give the possibility to filter on the web page and see only the +blog posts that fall under one of the options. You can choose from the +following options: + +* News & Announcements +* Features & Updates + +The 'Annual Report' category is reserved for the StarlingX chapter in the +Open Infrastructure Annual report that we are also re-posting on the StarlingX +website. + +Blog posts usually start with a one-sentence overview and teaser that is +formatted by using the '' tag at the end of that line. + +Once you filled out the above fields in the header and got your one-liner all +set, you can go ahead and type up the contents of your blog post using the +conventional markdown formatting. + +If you have an image file to add, you need to place the file in the +'static/img' folder. + +You can then insert the image into your blog post by using the following line: + +:: + + ![alt text](/img/the-file-name-of-your-image.jpg) + +Once you are done with formatting your blog post and happy with the content, you +need to upload it to GitHub and create a pull request. You can do that by using +git commands on your laptop or you can also use the GitHub web interface to add +files to the repository and create a pull request when you are ready. + +If you have an idea for a blog post and would like to get feedback from the +community about it, please send an email to the `starlingx-discuss mailing list +`_. + +If you need help with either writing and formatting the content or uploading +the final product to GitHub, please reach out to Ildiko Vancsa +(ildiko@openinfra.dev) for help. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 003654802..64939cc44 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -19,6 +19,7 @@ Contribute to documentation doc_contribute_guide api_contribute_guide release_note_contribute_guide + blog_contribute_guide ------------------ Contribute to code @@ -40,4 +41,4 @@ Additional resources -------------------- * `StarlingX wiki `_ -* :doc:`/developer_resources/index` \ No newline at end of file +* :doc:`/developer_resources/index`