How to contribute

--- tags: Content --- # How to contribute Here's how to contribute to the conda.org site. ## Submit via forms on the site. Certain types of site content, such as news items, events, and blog posts, support submitting content via web forms. Content submitted through these forms can provide either * A link to an external page for the item, along with some metadata about the item, the site will use when rendering the link to the item. * The text for the item, along with metadata about this tiem. In this case a new page will be created for the item in this web site. The text can contain Markdown if you want to format it. In both cases, the form will create and submit a GitHub pull request to add the information to the website. The pull request will be reviewed, and possibly modifed by a reviewer and then published to the website. Using the forms is the easiest way to add content. ## Submit via GitHub Pull Requests *Any* type of update can be submitted via pull requests. This can range from new pages on entirely new subjects, to updating website structure and styling. You can also submit news items, events, and so on this way. Doing this requires a knowledge of how Git works, and the ability to build the website locally so you can test your update before submitting it. It also requires following the [technical site guidelines](#Technical-Guidelines). ## What if I mess it up? Don't worry. All submissions, even by experienced contributors, are reviewed by others before being published to the production web site. # Building a local copy of the site Some updates require that you build a local copy of the website so that you can check your updates before submitting them. Here is how you do that. **Have the Technology Team write this part.** 1. Fork it. Include directions. 2. ... # Content Guidelines conda.org is a community site. The site's content is why people come to this site in the first place. ## Code of Conduct This site is governed by the conda Organization Code of Conduct. Content that violates the CoC will not be posted to the site. ## Relevance Content should be relevant to the conda community. Sometimes it's obvious when content is relevant and sometimes it's hard to tell. Let's take events as an example. 1. **Training events** that teach people how to use conda & friends for package and environment management, or how to build packages for the conda ecosystem are clearly relevant. 1. What about events like **PackagingCon**, a conference about software packaging that may or may not end up having conda-related content in a given year. Should that be listed? The answer is generally **Yes** because PackagingCon is directly relevant to what conda & friends do. 1. What about events like **PyData Portland meetups**, a regular and relatively small gathering of Python data afficianados in Portland Oregon. The answer is generally **No**, unless the # Technical Guidelines These guidelines are meant to make this site more maintainable / easier to update. ## Page / Path Naming Conventions When you specify a new page name / path there are two guidelines: * **Use all lower case letters.** * **Separate words with hyphens.** ## Page Metadata Each page has metadata at the top of it that is used to render / process the page in special ways. Metadata appears at the top of the file in this format: ``` --- title: "Dependency Graphs" tags: internals --- ``` Tags are written using YAML syntax and have the form `tag: value` or `tag: "value"` or `tag: 'value'` or `tag: 'value1', 'value2'` There are general tags that can be used on any page, and there are also specific sets of tags that can be used on specific types of pages like news items or events pages. If you add tags to a page, and the tags aren't reflected on the generated web site, then the most likely problem is one of these: - Special characters in unquoted tag value. A lot of things, including hyphens can cause problems. If in doubt, quote it. - Missing a space after the colon. That space matters. ### General metadata tags These tags can be used on any page. #### `title` * Required. * Title to show in the index page. * Could also become the page/tab title in the browser. * Would also be rendered at the top of this page. #### `tags` * Optional * Values come from a controlled list. * We may use tags to flag all pages that relate to a paraticular topic, and then link to all those pages from a single page about that topic. and so on. ## Favor Markdown over HTML The site uses [Markdown](https://www.markdownguide.org/basic-syntax/) to format content. Markdown is a simplified / reduced syntax for basic text formatting that supports the most common formatting options that people want in web pages. Markdown also enables you to embed HTML in your pages. Thus it is possible to have an entire Markdown page written in HTML. But don't: **If you have a choice of formatting something with Markdown or HTML, use Markdown.** Only use HTML when Markdown does not support what you need to do. HTML is much harder to read, and is much more intimidating for new contributors. ## Use relative links within the website **When linking to other pages in this site, use URLs that start with `/` instead of `https://conda.org/`** Clicking on a link in a locally built instance, should keep you in that instance. It should not take you to the production web site. ## Favor Font Awesome Icons over custom icons [Font Awesome](http://fontawesome.io/) is a standard collection of icons that cover a huge spectrum of what you need icons for on a web site. There are [around 1500 free icons](https://fontawesome.com/icons?d=gallery&m=free) to choose from. **If there is a Font Awesome icon for your situation, then use it.** Font Awesome icons can be rendered in multiple sizes, shown with or without borders, floated left or right, animated (spin them!), rotated, and integrated with Bootstrap. See the [Font Awesome Examples page](http://fontawesome.io/examples/) for how.