From 8d6016785ef5175b876ecd1b9775f66291faa4f4 Mon Sep 17 00:00:00 2001 From: terry Date: Wed, 23 Aug 2023 15:31:02 -0500 Subject: [PATCH 1/6] first additions to contrib --- CONTRIBUTING.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4126b9fa..6e4c579b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -143,3 +143,9 @@ HPC # i.e. the root of this repo * Any links to internal files must be the relative path to it from the referencing file, not the absolute path. * Code blocks will be automatically highlighted when rendered on the website, so please either use a code block or `inline` code whenever practical instead of a screenshot of a terminal. +## Blog posts + +### Formatting a blog post +Here is a brief overview on how to create and style a new blog post: + +First, you will need to add From 6c72d5a325829a078056744bc52ed599d90be7d6 Mon Sep 17 00:00:00 2001 From: terry Date: Wed, 23 Aug 2023 16:31:56 -0500 Subject: [PATCH 2/6] Added guide to create and format a blog --- CONTRIBUTING.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e4c579b1..f237f1713 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -145,7 +145,60 @@ HPC # i.e. the root of this repo ## Blog posts -### Formatting a blog post +### Creating a blog post Here is a brief overview on how to create and style a new blog post: -First, you will need to add +First, we need to create the Markdown file for the blog. The files name must follow the following styling. The files name must start with the date in this format XXXX-XX-XX- where each of the X sections correspond to this format YEAR-MONTH-DAY- and then is followed by a simple name that has something to do with the blog. Example Markdown file name: 2023-12-02-python_tutorial.md. The file name is prefaced with blog/ and added to the bottom of the Blog section within the mkdocs.yml file as follows: +```bash + nav: + - Home: index.md + - Blog: + - blog/2020-12-01-numba.md + - blog/2021-05-06-tf.md + - blog/2021-06-18-srun.md + - blog/2022-10-04-python2to3.md + - blog/2022-12-19-windows_ssh.md + - blog/index.md + - blog/2023-12-02-python_tutorial.md # <-- Added new Markdown file to the bottom of the Blog: section +``` + +Second, we need to add the author to the authors.yml file within the blog directory. Each author has four required elements. Their authors_name, name, description, and avatar. The authors_name will be referenced within the Markdown file later. The name is the authors full name. The description is set to "Author" and the avatar must be set to default.png as follows: + +```bash + authors_name_here: + name: John Doe + description: Author + avatar: default.png +``` + +Third, we need to add a new Markdown file to the posts directory within the blog directory. + +```bash + - HPC + - docs + - blog + - posts + - XXXX-XX-XX-new_file_goes_in_here.md +``` + +Next we have to format the blog post as follows: + +```bash + --- + date: XXXX-XX-XX + authors: + - authors_name_here # This is the authors_name we created earlier within the authors.yml file + --- + + # Title of the blog goes here with the "#" character included + + This will be the first paragraph of the blog post. This first paragraph will be previewed on the blog landing page. Try to make this first paragraph within three sentences or so to not clutter the blog landing page. Do not forget to add the "" after this first paragraph as this is what will seperate the first paragraph in the blog preview from the rest of the blog. + + # This seperates the blog preview from the rest of the blog + + This is where the rest of the blog content will go. + It is important to not forget to end the file with the "..." at the bottom with the exact spacing as shown below. + + ... + +``` \ No newline at end of file From 2fe380ab0ccf2e0c376517a4a729f9660d0ff5e5 Mon Sep 17 00:00:00 2001 From: terry Date: Thu, 31 Aug 2023 13:56:09 -0500 Subject: [PATCH 3/6] Updated blog creation guidlines --- CONTRIBUTING.md | 43 +++++++++++++------------------------------ 1 file changed, 13 insertions(+), 30 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f237f1713..7ba285a43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -148,46 +148,32 @@ HPC # i.e. the root of this repo ### Creating a blog post Here is a brief overview on how to create and style a new blog post: -First, we need to create the Markdown file for the blog. The files name must follow the following styling. The files name must start with the date in this format XXXX-XX-XX- where each of the X sections correspond to this format YEAR-MONTH-DAY- and then is followed by a simple name that has something to do with the blog. Example Markdown file name: 2023-12-02-python_tutorial.md. The file name is prefaced with blog/ and added to the bottom of the Blog section within the mkdocs.yml file as follows: +First, we need to create the Markdown file for the blog. The files name must follow the following styling. The files name must start with the date in this format XXXX-XX-XX- where each of the X sections correspond to this format YEAR-MONTH-DAY- and then is followed by a simple name that has something to do with the blog. Example Markdown file name: 2023-12-02-python_tutorial.md. The file must be placed within the posts directory which can be found as follows: + ```bash - nav: - - Home: index.md - - Blog: - - blog/2020-12-01-numba.md - - blog/2021-05-06-tf.md - - blog/2021-06-18-srun.md - - blog/2022-10-04-python2to3.md - - blog/2022-12-19-windows_ssh.md - - blog/index.md - - blog/2023-12-02-python_tutorial.md # <-- Added new Markdown file to the bottom of the Blog: section + - HPC + - docs + - blog + - posts + - XXXX-XX-XX-new_file_goes_in_here.md ``` -Second, we need to add the author to the authors.yml file within the blog directory. Each author has four required elements. Their authors_name, name, description, and avatar. The authors_name will be referenced within the Markdown file later. The name is the authors full name. The description is set to "Author" and the avatar must be set to default.png as follows: +Second, we need to add the author to the authors.yml file within the blog directory. Each author has four required elements. Their's the authors_name, name, description, and avatar. The authors_name is going to be the author's fullname in all lowercase with no space (example: johndoe) and this will be referenced within the blogs Markdown file later. The name is the authors full name. The description must be set to "Author" and the avatar must be set to http://nrel.github.io/HPC/blog/assets/avatar/default.png as follows: ```bash - authors_name_here: + johndoe: # This is the authors_name name: John Doe - description: Author - avatar: default.png -``` - -Third, we need to add a new Markdown file to the posts directory within the blog directory. - -```bash - - HPC - - docs - - blog - - posts - - XXXX-XX-XX-new_file_goes_in_here.md + description: Author + avatar: http://nrel.github.io/HPC/blog/assets/avatar/default.png ``` -Next we have to format the blog post as follows: +Lastly, we have to format the blog post as follows: ```bash --- date: XXXX-XX-XX authors: - - authors_name_here # This is the authors_name we created earlier within the authors.yml file + - authors_name # This is the authors_name we created earlier within the authors.yml file --- # Title of the blog goes here with the "#" character included @@ -197,8 +183,5 @@ Next we have to format the blog post as follows: # This seperates the blog preview from the rest of the blog This is where the rest of the blog content will go. - It is important to not forget to end the file with the "..." at the bottom with the exact spacing as shown below. - - ... ``` \ No newline at end of file From 1a3b0e60b542b4384b36b618e8e7f45c7db24ee2 Mon Sep 17 00:00:00 2001 From: terry Date: Thu, 31 Aug 2023 13:58:18 -0500 Subject: [PATCH 4/6] Used the correct there --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ba285a43..1c61730e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -148,7 +148,7 @@ HPC # i.e. the root of this repo ### Creating a blog post Here is a brief overview on how to create and style a new blog post: -First, we need to create the Markdown file for the blog. The files name must follow the following styling. The files name must start with the date in this format XXXX-XX-XX- where each of the X sections correspond to this format YEAR-MONTH-DAY- and then is followed by a simple name that has something to do with the blog. Example Markdown file name: 2023-12-02-python_tutorial.md. The file must be placed within the posts directory which can be found as follows: +First, we need to create the Markdown file for the blog. The file's name must follow the following styling. The files name must start with the date in this format XXXX-XX-XX- where each of the X sections correspond to this format YEAR-MONTH-DAY- and then is followed by a simple name that has something to do with the blog. Example Markdown file name: 2023-12-02-python_tutorial.md. The file must be placed within the posts directory which can be found as follows: ```bash - HPC @@ -158,7 +158,7 @@ First, we need to create the Markdown file for the blog. The files name must fol - XXXX-XX-XX-new_file_goes_in_here.md ``` -Second, we need to add the author to the authors.yml file within the blog directory. Each author has four required elements. Their's the authors_name, name, description, and avatar. The authors_name is going to be the author's fullname in all lowercase with no space (example: johndoe) and this will be referenced within the blogs Markdown file later. The name is the authors full name. The description must be set to "Author" and the avatar must be set to http://nrel.github.io/HPC/blog/assets/avatar/default.png as follows: +Second, we need to add the author to the authors.yml file within the blog directory. Each author has four required elements. There's the authors_name, name, description, and avatar. The authors_name is going to be the author's fullname in all lowercase with no space (example: johndoe) and this will be referenced within the blogs Markdown file later. The name is the authors full name. The description must be set to "Author" and the avatar must be set to http://nrel.github.io/HPC/blog/assets/avatar/default.png as follows: ```bash johndoe: # This is the authors_name From 0ac90370a1e6251a375ba8f0c3f7cf07bdbb8853 Mon Sep 17 00:00:00 2001 From: terry Date: Mon, 18 Sep 2023 15:32:05 -0500 Subject: [PATCH 5/6] Adding in requested changes --- CONTRIBUTING.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c61730e3..8a33bbcdc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -146,19 +146,17 @@ HPC # i.e. the root of this repo ## Blog posts ### Creating a blog post -Here is a brief overview on how to create and style a new blog post: +Here is a brief overview on how to create and style a new blog post for Github Pages: -First, we need to create the Markdown file for the blog. The file's name must follow the following styling. The files name must start with the date in this format XXXX-XX-XX- where each of the X sections correspond to this format YEAR-MONTH-DAY- and then is followed by a simple name that has something to do with the blog. Example Markdown file name: 2023-12-02-python_tutorial.md. The file must be placed within the posts directory which can be found as follows: +First, we need to create the Markdown file for the blog. The file's name must start with the date in this format XXXX-XX-XX- where each of the X sections correspond to this format YEAR-MONTH-DAY- and then is followed by a short, descriptive name. Example Markdown file name: 2023-12-02-python_tutorial.md. The file must be placed within the `posts` directory which can be found by following this directory path: ```bash - - HPC - - docs - - blog - - posts - - XXXX-XX-XX-new_file_goes_in_here.md + - HPC/docs/blog/posts/XXXX-XX-XX-new_file_goes_in_here.md ``` -Second, we need to add the author to the authors.yml file within the blog directory. Each author has four required elements. There's the authors_name, name, description, and avatar. The authors_name is going to be the author's fullname in all lowercase with no space (example: johndoe) and this will be referenced within the blogs Markdown file later. The name is the authors full name. The description must be set to "Author" and the avatar must be set to http://nrel.github.io/HPC/blog/assets/avatar/default.png as follows: +Note: You do not have to add this file to the mkdocs.yml file. + +Second, we need to add a new author to the authors.yml file within the blog directory. If your author has been added to the authors.yml file already then you may skip this step and use the existing authors_name in the next step. To add a new author it will include four required elements. There's the authors_name, name, description, and avatar. The authors_name is going to be the author's fullname in all lowercase with no space (example: johndoe) and this will be referenced within the blog's Markdown file later. The name is the author's full name. The description must be set to "Author" and the avatar must be set to http://nrel.github.io/HPC/blog/assets/avatar/default.png as follows: ```bash johndoe: # This is the authors_name From 4c35b69f87b6e495b66422d8f886f8cd9cdccb6b Mon Sep 17 00:00:00 2001 From: terry Date: Mon, 18 Sep 2023 15:35:31 -0500 Subject: [PATCH 6/6] fixed spacing on last code block --- CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a33bbcdc..d09597acb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -176,7 +176,10 @@ Lastly, we have to format the blog post as follows: # Title of the blog goes here with the "#" character included - This will be the first paragraph of the blog post. This first paragraph will be previewed on the blog landing page. Try to make this first paragraph within three sentences or so to not clutter the blog landing page. Do not forget to add the "" after this first paragraph as this is what will seperate the first paragraph in the blog preview from the rest of the blog. + This will be the first paragraph of the blog post.\n + This first paragraph will be previewed on the blog landing page.\n + Try to make this first paragraph within three sentences or so to not clutter the blog landing page.\n + Do not forget to add the "" after this first paragraph as this is what will seperate the first paragraph in the blog preview from the rest of the blog. # This seperates the blog preview from the rest of the blog