|
| 1 | + |
| 2 | +# Guide to Contributing |
| 3 | +How to contribute to the [scikit-learn.org blog](https://blog.scikit-learn.org). |
| 4 | +*** |
| 5 | + |
| 6 | +**Table of Contents** |
| 7 | +- [Blog Standards](https://github.com/scikit-learn/blog/blob/main/CONTRIBUTING.md#blog-standards) |
| 8 | + - [Categories & Tags](https://github.com/scikit-learn/blog/blob/main/CONTRIBUTING.md#categories--tags) |
| 9 | +- [Installation](https://github.com/scikit-learn/blog/blob/main/CONTRIBUTING.md#installation) |
| 10 | +- [Adding a New Post](https://github.com/scikit-learn/blog/blob/main/CONTRIBUTING.md#adding-a-new-post) |
| 11 | + - [Setup](https://github.com/scikit-learn/blog/blob/main/CONTRIBUTING.md#setup) |
| 12 | + - [Submitting Your Blog Post](https://github.com/scikit-learn/blog/blob/main/CONTRIBUTING.md#submitting-your-blog-post) |
| 13 | + - [Formatting Your Blog Post](https://github.com/scikit-learn/blog/blob/main/CONTRIBUTING.md#formatting-your-blog-post) |
| 14 | +<br><br> |
| 15 | + |
| 16 | +# Blog Standards |
| 17 | +This section contains information around the scikit-learn @ Fondation Inria's standards and guidelines. |
| 18 | + |
| 19 | +## Categories & Tags |
| 20 | +Categories and Tags help us organize our blog by grouping related content to make it easier to discover. |
| 21 | + |
| 22 | +:warning:**NOTE**:warning: Individual Category *(blog/category/name.md)* and Tag *(blog/tag/name.md)* pages are automatically generated by a Github Action. Please do not manually add add markdown pages. |
| 23 | + |
| 24 | +### Categories |
| 25 | +Categories are broad groupings of posts. A post should have only one category. If the post could potentially fall under multiple categories, please select the one that best describes it. |
| 26 | + |
| 27 | + *Example Categories:* Updates, Events, Team |
| 28 | + |
| 29 | +### Tags |
| 30 | +Tags describe specific details of a post. They help to link related posts together and aid in user search. A post can have multiple tags or no tags. While there is no strict limit, we recommend using no more than 10 tags per post. |
| 31 | + |
| 32 | + *Example Tags:* Sprints, Community, Open Source, New Member, Machine Learning, New Feature |
| 33 | +<br><br> |
| 34 | + |
| 35 | + |
| 36 | + |
| 37 | +# Installation |
| 38 | +Instructions to build and test the [blog.scikit-learn.org](https://scikit-learn.org/blog) site locally. |
| 39 | + |
| 40 | +## Installing Ruby & Jekyll |
| 41 | +If this is your first time using Jekyll, please follow the [Jekyll docs](https://jekyllrb.com/docs/installation/) and make sure your local environment (including Ruby) is setup correctly. |
| 42 | + |
| 43 | +## Deployment |
| 44 | +To run the theme locally: |
| 45 | +1. Navigate to the theme directory and run `bundle install` to install the dependencies (if you get errors, delete Gemfile.lock and try again). |
| 46 | +2. Next, run `jekyll serve` or `bundle exec jekyll serve` to start the Jekyll server. |
| 47 | +3. Visit the site in your browser via [http://localhost:4000](http://localhost:4000). |
| 48 | + |
| 49 | +For more information, check the [Deployment Methods](https://jekyllrb.com/docs/deployment-methods/) page on the Jekyll website. |
| 50 | + |
| 51 | +### Theme Documentation |
| 52 | +This blog is uses the [Minimal Mistakes Jekyll Theme](https://github.com/mmistakes/minimal-mistakes). For more information on configuration/customization, please reference the [theme documentation](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/). |
| 53 | +<br><br> |
| 54 | + |
| 55 | + |
| 56 | + |
| 57 | + |
| 58 | +# Adding a New Post |
| 59 | + |
| 60 | +## Setup |
| 61 | +This sections contains instructions to add a new blog post to the scikit-learn @ Fondation Inria. |
| 62 | + |
| 63 | +Before adding a post, you must have: |
| 64 | +- A Github account |
| 65 | +<br> |
| 66 | + |
| 67 | +## Submitting Your Blog Post |
| 68 | +Refer to the [blog post template](https://github.com/scikit-learn/blog/blob/main/_posts/templates/2022-01-01-template-post.markdown). |
| 69 | + |
| 70 | +1. First, fork the [scikit-learn/blog](https://github.com/scikit-learn/blog) repository. |
| 71 | +2. Within your forked repository, make a copy of the [Blog Post Template](https://github.com/scikit-learn/blog/blob/main/_posts/templates/2022-01-01-template-post.markdown). |
| 72 | + - Save the post in the ["_posts/"](https://github.com/scikit-learn/blog/blob/main/_posts/) folder, formatted as `YYYY-MM-DD-post-title.md`. |
| 73 | + - Format your blog post using the instructions in the [Formatting Your Blog Post](https://github.com/scikit-learn/blog/blob/main/README.md#formatting-your-blog-post) section. |
| 74 | +4. Go to Pull Requests and do a New Pull request. |
| 75 | +5. Create a pull request. |
| 76 | +<br> |
| 77 | + |
| 78 | + |
| 79 | +## Formatting Your Blog Post |
| 80 | + |
| 81 | +### 1) Update the Post's Front Matter |
| 82 | +The purpose of front matter is to set variables and metadata on the site's pages. |
| 83 | + |
| 84 | +<details> |
| 85 | +<summary> Click to Expand </summary> |
| 86 | + |
| 87 | + 1. **Add Post Information** |
| 88 | + - *title:* Add the title of your blog post in double quotes, |
| 89 | + - `title: "Example Post Title"` (with quotes) |
| 90 | + - *date:* Add the date of posting. This helps to ensure our blog displays posts are sorted correctly and are displayed in a sequential order. |
| 91 | + - `date: Month Name, Day, Year` (no quotes) <br> |
| 92 | + |
| 93 | + 2. **Add Post Category and Tags:** Categories and tags help us organize our blog by grouping related content to make it easier to discover. Check the [Blog Standards](https://github.com/scikit-learn/blog#blog-standards) section for more information. |
| 94 | + - *categories:* A post should have only one category. Format categories in titlecase without dashes (Ex. "Open Source" instead of "open-source") |
| 95 | + - *tags:* Tags describe specific details of a post. They help to link related posts together and aid in user search. |
| 96 | + -  |
| 97 | + 3. **Add Featured Image** |
| 98 | + - *featured-image:* First, place the image in the [assets/images/posts_images/](https://github.com/scikit-learn/blog/tree/main/assets/images/posts_images) folder. Set the featured-image variable to the base image name, omiting the full path. |
| 99 | + - `featured-image: image-name.png` (no quotes) |
| 100 | + 4. **Add Author Information** |
| 101 | + - The *postauthors* field can accomodate multiple authors. Each postauthor can use the following four variables, but only the `name` field is required. |
| 102 | + - *name:* (required) |
| 103 | + - `name: Author Name` (no quotes) |
| 104 | + - *website:* (optional) Link attached to author name. Can be any relevant link. |
| 105 | + - `website: https://github.com` (no quotes) |
| 106 | + - *email:* (optional) Appears as an email icon after author name. |
| 107 | + - `email: [email protected]` (no quotes) |
| 108 | + - *image:* (optional) Author headshot, appears before author name. First, place the image in the [assets/images/author_images/](https://github.com/scikit-learn/blog/tree/main/assets/images/author_images) folder. Set the image variable to the base image name, omiting the full path. |
| 109 | + - `image: image-name.png` (no quotes) |
| 110 | + - Single Author Post | Multiple Author Post |
| 111 | + :-------------------------:|:-------------------------: |
| 112 | +  |  |
| 113 | +</details> |
| 114 | +<br> |
| 115 | + |
| 116 | + |
| 117 | +### 2) Add post content. |
| 118 | +You can format your post using Markdown. Click to expand to view basic formatting suggestions or visit the [Markdown Guide](https://www.markdownguide.org/) for more examples. |
| 119 | +<details> |
| 120 | +<summary> Click to Expand </summary> |
| 121 | + |
| 122 | + #### Headings |
| 123 | + Use the **\#** symbol to format header text. |
| 124 | + ``` |
| 125 | + # Heading 1 |
| 126 | + ## Heading 2 |
| 127 | + ### Heading 3 |
| 128 | + #### Heading 4 |
| 129 | + ##### Heading 5 |
| 130 | + ###### Heading 6 |
| 131 | + ``` |
| 132 | + |
| 133 | + #### Text Emphasis |
| 134 | + Use the __\*__ or **\_** symbols around words or phrases to add **bolding** or _italics_, or _even **bold** within italics_! |
| 135 | + ``` |
| 136 | + _Italic text_ |
| 137 | + *Italic text* |
| 138 | + __Bold text__ |
| 139 | + **Bold text** |
| 140 | + _You can even add **bold text** within italics_ |
| 141 | + ``` |
| 142 | + |
| 143 | + #### Lists |
| 144 | + Add unordered lists: |
| 145 | + ``` |
| 146 | + - Item 1 |
| 147 | + - Item 2 |
| 148 | + ``` |
| 149 | + Or ordered lists: |
| 150 | + ``` |
| 151 | + 1. Item 1 |
| 152 | + 2. Item 2 |
| 153 | + ``` |
| 154 | + If you are adding paragraphs between list items, be sure to indent each paragragh by four spaces. |
| 155 | + ``` |
| 156 | + 1. Item 1 |
| 157 | + Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Feugiat in fermentum posuere urna nec. Nibh tellus molestie nunc non blandit. Dui id ornare arcu odio ut sem nulla. |
| 158 | + Non curabitur gravida arcu ac. Ut sem viverra aliquet eget sit amet. Morbi tincidunt ornare massa eget egestas purus viverra accumsan in. Vulputate eu scelerisque felis imperdiet proin fermentum leo vel. Tincidunt augue interdum velit euismod in pellentesque massa. Interdum velit laoreet id donec ultrices tincidunt. |
| 159 | + 2. Item 2 |
| 160 | + ``` |
| 161 | + |
| 162 | + #### Links |
| 163 | + Add a link with [custom text](https://blog.scikit-learn.org). |
| 164 | + ``` |
| 165 | + [link text](https://url.com) |
| 166 | + ``` |
| 167 | + |
| 168 | + #### Images |
| 169 | + There are a few ways to add images to your post. First, place the image in the [/assets/images/posts_images/](https://github.com/scikit-learn/blog/tree/main/assets/images/posts_images) folder, then adding the following code. </br> |
| 170 | + |
| 171 | + ##### Add an Image |
| 172 | + ``` |
| 173 | +  |
| 174 | + ``` |
| 175 | + |
| 176 | + ##### Customize Image Size |
| 177 | + Adjust the width and height of your image. |
| 178 | + ``` |
| 179 | + <img src="/blog/assets/images/posts_images/sample-image.png" width="200" height="100"> |
| 180 | + ``` |
| 181 | + |
| 182 | + ##### Add an Image Caption |
| 183 | + - Within **img src**, replace _sample-image.jpg_ with the name of the image and update the _alt_ to be a short (2-4 word) description of the image. |
| 184 | + - Update the **Photo Credit** _caption-link_ and replace _Credit Link Text_ with the source name. |
| 185 | + ``` |
| 186 | + <figure> |
| 187 | + <img src="/blog/assets/images/posts_images/sample-image.jpg" |
| 188 | + alt="short description" max-width="50%" max-height="50%" /> |
| 189 | + <figcaption> |
| 190 | + Photo Credit: <a href="https://caption-link.com">Credit Link Text</a> |
| 191 | + </figcaption> |
| 192 | + </figure> |
| 193 | + ``` |
| 194 | + |
| 195 | + ##### Add a Link to an Image |
| 196 | + Update the _image_link_. The _Hover Text_ will be shown when a mouse hover's over the image. |
| 197 | + ``` |
| 198 | + [](https://image-link.com) |
| 199 | + ``` |
| 200 | + |
| 201 | + |
| 202 | + #### Text Highlighting |
| 203 | + |
| 204 | + <img src="/assets/images/brand_images/highlighted-text.png" width="300"> |
| 205 | + |
| 206 | + ``` |
| 207 | + <span style="background-color: #CAE9F5;"> |
| 208 | + [Data Umbrella Interview: Juan Martín Loyola](https://blog.dataumbrella.org/jmloyola-opensource-experience) |
| 209 | + </span> |
| 210 | + ``` |
| 211 | +</details> |
0 commit comments