CONTRIBUTING.md

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