|
1 | 1 | # Basil.js |
2 | 2 |
|
3 | | -[](https://travis-ci.org/basiljs/basiljs.github.io) |
| 3 | +[](https://travis-ci.org/basiljs/basiljs.github.io) [](https://app.netlify.com/sites/basiljs2/deploys) |
| 4 | + |
| 5 | +Hosted on: |
| 6 | + |
| 7 | +[](https://basiljs2.netlify.com/) |
4 | 8 |
|
5 | 9 | This repo holds the [site/docs for Basil.js](https://basiljs.github.io/). The current state of development (develop branch) can be found here [basiljs2.netlify.com](https://basiljs2.netlify.com/) |
| 10 | +## Update Basil API |
| 11 | + |
| 12 | +If there are changes to the API of Basil.js you can update the data on this repo as follows. |
| 13 | + |
| 14 | +```bash |
| 15 | + |
| 16 | +git pull git@github.com:basiljs/basiljs.github.io.git |
| 17 | +cd basiljs.github.io |
| 18 | +# get all branches |
| 19 | +git fetch -a |
| 20 | +# get into the develop branch |
| 21 | +git checkout -b develop origin/develop |
| 22 | +# now make your new branch based on develop |
| 23 | +git checkout -b chore/update-docs |
| 24 | +# build the new data source for the site |
| 25 | +# This will: |
| 26 | + |
| 27 | +# - Pull the Basil.js' branch `develop` with npm from GitHub (eventually this should be the master, not the develop branch). |
| 28 | +# - Generate the file `./build-scripts/api/data.json` from `./node_modules/basiljs/basil.js` using [documentation.js](http://documentation.js.org/). |
| 29 | +# - Generate the following files for the index. |
| 30 | +# + `./_data/categories.json` |
| 31 | +# + `./_data/cats-and-subcats.json` |
| 32 | +# - Also generate all the files for the subpages of `_source/reference`. |
| 33 | +npm run build:api-markup |
| 34 | +# After that you can just commit all the changes and push it the repo again. Netlify will take care of the Jekyll build. |
| 35 | +# Only add the files you really want to. |
| 36 | +# Adding all with `git add .` is acutally not the right way |
| 37 | +# use gits interactive mode or some more specific paths then `.` |
| 38 | +git add -i |
| 39 | +git commit -m "chore: Update Basil.js api to latest state [Add your favorite emoji here]" |
| 40 | +# push current HEAD to remote |
| 41 | +git push -u origin HEAD |
| 42 | +# Now go to the GitHub UI and create your PR |
| 43 | +``` |
6 | 44 |
|
7 | | -## Deploy |
| 45 | +This repo holds the [site/docs for Basil.js](https://basiljs.github.io/). The current state of development (develop branch) can be found here [basiljs2.netlify.com](https://basiljs2.netlify.com/) |
8 | 46 |
|
9 | | -If there are some changed to the API of Basil.js you can update the data on this repo as follows. |
| 47 | +## Development |
10 | 48 |
|
11 | | - npm run build |
| 49 | +To build these docs we are using [Webpack](https://webpack.js.org/) and [Jekyll](https://jekyllrb.com/). You need both of these to develop on this. |
12 | 50 |
|
13 | | -This will: |
| 51 | +- Create a new branch based on branch `develop` (see the code above for a how to 👆). |
| 52 | +- Do your thing |
| 53 | +- Create a pull request against develop |
14 | 54 |
|
15 | | -- Pull the branch develop with npm from GitHub. |
16 | | -- Generate the file `./.bin/api/data.json` from `./node_modules/basiljs/basil.js` using [documentation.js](http://documentation.js.org/). |
17 | | -- Generate the following files for the index. |
18 | | - + `./_data/categories.json` |
19 | | - + `./_data/cats-and-subcats.json` |
20 | | -- Also generate all the files for the subpages. |
| 55 | +Netlify will create a branch and deploy preview for you and you can see your changes online. Every push to your branch will trigger a new build and will be linked on the PR page. |
21 | 56 |
|
22 | | -After that you can just commit all the changes and push it the repo again. GitHub pages will take care of the jekyll build. |
| 57 | +To develop locally take a look at the steps below. 👇 |
23 | 58 |
|
| 59 | +### Markup + SCSS |
24 | 60 |
|
25 | | -## Development |
| 61 | +Most of the Jekyll [liquid magic](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) happens in `./_source`. |
26 | 62 |
|
27 | | -To build these docs we are using [Node.js](https://nodejs.org/en/) and [Jekyll](https://jekyllrb.com/). You need both of them installed to develop on this. |
| 63 | +To develop in this run: |
28 | 64 |
|
29 | | -In the `.bin/` folder you have the scripts to generate the files for the reference. The entry point is `index.js`. |
| 65 | +```bash |
| 66 | +# once |
| 67 | +bundle install |
| 68 | +bundle update |
| 69 | +# whenever you want to work on the markup/content |
| 70 | +# (the --limit_posts 1 --incremental flags are needed |
| 71 | +# because we have lots of pages and need to speedup the build) |
| 72 | +bundle exec jekyll serve --livereload --limit_posts 1 --incremental |
| 73 | +``` |
30 | 74 |
|
31 | | -Most of the jekyll [liquid magic](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) happens in `./index.html`, `_includes/entry-card.html`. |
| 75 | +### Javascript |
32 | 76 |
|
33 | | -To develop in this run: |
| 77 | +To work on the Javasscript of the site you need to run |
| 78 | + |
| 79 | +```bash |
| 80 | +# once |
| 81 | +# needs npm v5.7 or higer |
| 82 | +npm ci |
| 83 | +# when you develop on it |
| 84 | +# (starts the webpack dev watch build toolchain) |
| 85 | +npm run webpack:dev |
| 86 | +``` |
| 87 | + |
| 88 | +## Recipes |
| 89 | + |
| 90 | +Resize and crop multiple images using [`mogrify`](https://www.imagemagick.org/script/mogrify.php) |
| 91 | + |
| 92 | +```bash |
| 93 | +mogrify -resize 320x180^ -gravity Center -extent 320x180 -quality 100 -format png ./*/thumbnail.jpg |
34 | 94 |
|
35 | | - bundle install |
36 | | - bundle update |
37 | | - bundle exec jekyll serve --livereload |
| 95 | +``` |
38 | 96 |
|
39 | 97 | ## License |
40 | 98 |
|
|
0 commit comments