From f7b625b1b77d48a8177af4c7a167857366d54737 Mon Sep 17 00:00:00 2001 From: Ivan Ogasawara Date: Wed, 31 Jul 2024 17:27:55 -0400 Subject: [PATCH 1/2] docs: Add contributing guide --- CONTRIBUTING.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..3074893c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,95 @@ +# Contributing Guide for Open Science Labs Blog + +## Getting Started + +To contribute to the Open Science Labs blog, you should first fork the +repository and clone it locally. Follow these steps to set up your local +development environment: + +```bash +# Clone your fork of the repository +$ git clone https://github.com/MY-USER-NAME/opensciencelabs.github.io +$ cd opensciencelabs.github.io + +# Add the original project as an upstream remote +$ git remote add upstream https://github.com/opensciencelabs/opensciencelabs.github.io +$ git fetch --all +``` + +_Note: Replace `MY-USER-NAME` with your GitHub username._ + +## Setting Up the Environment + +Set up the Conda environment to manage the dependencies for the blog: + +```bash +# Create and activate the Conda environment +$ mamba env create --file conda/dev.yaml +$ conda activate osl-web +``` + +This will create a new Conda environment named `osl-web` with all necessary +dependencies and activate it. + +## Developing Blog Posts + +### Development Commands + +- **Previewing Changes:** Use `makim pages.preview` to run a local server for + previewing the blog and other pages. +- **Building the Site:** Before pushing changes to GitHub, build the site using + `makim pages.build` to ensure everything is compiled correctly. + +### Creating a New Blog Post + +1. **Prepare the Blog Post:** + + - Navigate to `pages/blog` and create a new folder with a slugified version + of your blog post's title. Use + [https://slugify.online/](https://slugify.online/) to generate a slug. + - Inside this folder, create your blog post file: + - For Markdown: `index.md` + - For Jupyter Notebooks: `index.ipynb` (use Jupyter Lab to create this + directly) + +2. **Include a Header Image:** + - Place a header image (either `header.png` or `header.jpg`) in your blog + post folder. Make sure the image is under a free license. + +### Metadata and Formatting + +- **Markdown Posts:** Add a metadata block at the beginning of your `index.md` + file: + + ```markdown + --- + title: "Title of Your Blog Post" + slug: "slug-of-your-blog-post" + date: YYYY-MM-DD + authors: ["Author Name"] + tags: ["tag1", "tag2"] + categories: ["category1", "category2"] + description: "Short description of the blog post." + thumbnail: "/path/to/header.jpg" + template: "blog-post.html" + --- + ``` + +- **Jupyter Notebook Posts:** The first cell of your `index.ipynb` should be in + `raw` mode containing the same metadata as above. + +3. **Building and Viewing:** + - If using a Jupyter Notebook, run `makim pages.build` to convert the + notebook into a Markdown file (`index.md`). + - Add the generated `index.md` to your repository as it will be used to + render the webpage. + +## Final Steps + +Before submitting your blog post: + +- Ensure all files are added to your repository. +- Submit a pull request to the main `opensciencelabs.github.io` repository for + review. + +Thank you for contributing to the Open Science Labs blog! From f1fa9f3f1354a8010699acca5418bd682438c2f9 Mon Sep 17 00:00:00 2001 From: Ivan Ogasawara Date: Wed, 31 Jul 2024 17:29:35 -0400 Subject: [PATCH 2/2] fix header path in the example --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3074893c..a0dbe1ab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,7 +70,7 @@ dependencies and activate it. tags: ["tag1", "tag2"] categories: ["category1", "category2"] description: "Short description of the blog post." - thumbnail: "/path/to/header.jpg" + thumbnail: "/header.jpg" template: "blog-post.html" --- ```