diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4126b9fa..d09597acb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -143,3 +143,46 @@ 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 + +### Creating a 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 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 +``` + +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 + name: John Doe + description: Author + avatar: http://nrel.github.io/HPC/blog/assets/avatar/default.png +``` + +Lastly, we have to format the blog post as follows: + +```bash + --- + date: XXXX-XX-XX + authors: + - 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 + + 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 + + This is where the rest of the blog content will go. + +``` \ No newline at end of file