CONTRIBUTING.md

   1 # Developer notes
   2
   3 ## Gitpod
   4
   5 This repository supports contribution using [gitpod](https://gitpod.io) which is online IDE using [Theia](https://github.com/eclipse-theia/theia).
   6
   7 To open-up the environment simple natigate on https://gitpod.io/#https://github.com/rstacruz/cheatsheets
   8
   9 Or using a button:<br>
  10 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/rstacruz/cheatsheets)
  11
  12 ### Preview built website
  13
  14 To preview the website you need to first build it then you can navigate to file that you are trying to contribute and preview directly.
  15
  16 <img src='_docs/images/gitpod_preview_tut.png' width=828 height=459/>
  17
  18 ## Starting a local instance
  19
  20 This starts Jekyll and Parcel. This requires recent versions of [Node.js], [Yarn], [Ruby] and [Bundler] installed.
  21
  22 ```bash
  23 yarn install
  24 bundle install
  25 env PORT=4001 yarn run dev
  26 ```
  27
  28 [node.js]: https://nodejs.org/en/download/package-manager/
  29 [ruby]: https://www.ruby-lang.org/en/documentation/installation/
  30 [yarn]: https://yarnpkg.com/en/docs/install
  31 [bundler]: https://bundler.io/
  32
  33 ### Docker
  34
  35 You can also run a local instance using Docker. This is the preferred method, especially for Windows.
  36 You only need to install Docker ([macOS](https://docs.docker.com/docker-for-mac/install/), [Windows](https://docs.docker.com/docker-for-windows/install/), [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/), [Arch Linux](https://www.archlinux.org/packages/community/x86_64/docker/), [other](https://www.docker.com/community-edition#download)).
  37
  38 First time setup:
  39
  40 ```bash
  41 # Build images (takes ~12mins)
  42 docker-compose build
  43
  44 # First-time setup
  45 docker-compose run --rm web bundle install && docker-compose run --rm web yarn install
  46 ```
  47
  48 Starting the server:
  49
  50 ```bash
  51 docker-compose up
  52 ```
  53
  54 ## CSS classes
  55
  56 See <https://devhints.io/cheatsheet-styles> for a reference on styling.
  57
  58 ## JavaScript
  59
  60 When updating JavaScript, be sure Parcel is running (`yarn dev` takes care of this).
  61
  62 This auto-updates `/assets/packed/` and `_includes/2017/critical/` with sources in `_parcel/`.
  63
  64 Before committing, run `yarn parcel:build` first.
  65
  66 ## JavaScript tests
  67
  68 There are also automated tests:
  69
  70 ```
  71 yarn run test --watch
  72 ```
  73
  74 ## Frontmatter
  75
  76 Each sheet supports these metadata:
  77
  78 ```yml
  79 ---
  80 title: React.js
  81 layout: 2017/sheet # 'default' | '2017/sheet'
  82
  83 # Optional:
  84 category: React
  85 updated: 2020-06-14
  86 ads: false # Add this to disable ads
  87 weight: -5 # lower number = higher in related posts list
  88 deprecated: true # Don't show in related posts
  89 deprecated_by: /enzyme # Point to latest version
  90 prism_languages: [vim] # Extra syntax highlighting
  91 intro: |
  92   This is some *Markdown* at the beginning of the article.
  93 tags:
  94   - WIP
  95   - Featured
  96
  97 # Special pages:
  98 # (don't set these for cheatsheets)
  99 type: home # home | article | error
 100 og_type: website # opengraph type
 101 ---
 102
 103 ```
 104
 105 ## Prism languages
 106
 107 For supported prism languages:
 108
 109 - <https://github.com/PrismJS/prism/tree/gh-pages/components>
 110
 111 ## Setting up redirects
 112
 113 This example sets up a redirect from `es2015` to `es6`:
 114
 115 ```yml
 116 # /es2015.md
 117 ---
 118 title: ES2015
 119 category: Hidden
 120 redirect_to: /es6
 121 ---
 122
 123 ```
 124
 125 ## Localizations
 126
 127 See `_data/content.yml` for chrome strings.
 128
 129 ## Forking
 130
 131 So you want to fork this repo? Sure, here's what you need to know to whitelabel this:
 132
 133 - It's all GitHub pages, so the branch has to be `gh-pages`.
 134 - All other GitHub pages gotchas apply (CNAME, etc).
 135 - Edit everything in `_data/` - this holds all 'config' for the site: ad IDs, strings, etc.
 136 - Edit `_config.yml` as well, lots of things may not apply to you.
 137
 138 ## CloudFlare purging
 139
 140 The site devhints.io is backed by CloudFlare. Updates will take 2 days to propagate to the website by default. To make sure recent changes will propagate, use this helper script. It will give instructions on how manual selective cache purging can be done.
 141
 142 ```bash
 143 ./_support/cf-purge.sh
 144 ```
 145
 146 ## SEO description
 147
 148 There are multiple ways to set meta description.
 149
 150 ### Keywords (and intro)
 151
 152 Set `keywords` (and optionally `intro`). This is the easiest and the preferred
 153 way for now.
 154
 155 ```
 156 React cheatsheet - devhints.io
 157 ------------------------------
 158 https://devhints.io/react ▼
 159 React.Component · render() · componentDidMount() · props/state · React is a
 160 JavaScript library for building web...
 161 ```
 162
 163 ### Description (and intro)
 164
 165 Set `description` (and optionally `intro`)
 166
 167 ```
 168 React cheatsheet - devhints.io
 169 ------------------------------
 170 https://devhints.io/react ▼
 171 One-page reference to React and its API. React is a JavaScript library for
 172 building web user interfaces...
 173 ```
 174
 175 ### Intro only
 176
 177 If you left out `description` or `keywords`, a default description will be added.