diff --git a/.tool-versions b/.tool-versions new file mode 100644 index 0000000000..bbe5951980 --- /dev/null +++ b/.tool-versions @@ -0,0 +1 @@ +ruby 2.7.5 \ No newline at end of file diff --git a/README.md b/README.md index 08fc9c331b..10f0a3661f 100644 --- a/README.md +++ b/README.md @@ -3,29 +3,11 @@ The Artsy OSS page and the blog runs on top of a default jekyll install. If you would like an overview of jekyll, their [website rocks](http://jekyllrb.com/). -## Setup +## Documentation -``` -git clone git@github.com:artsy/artsy.github.io.git -cd artsy.github.io -bundle -bundle exec rake bootstrap -bundle exec rake build -``` - -### Common issues ⚠️ - -
Issues installing `therubyracer` and/or `v8` dependencies -Some combination of the following might help resolve issues with installing these dependencies: - -- make sure you have a ruby version that works (e.g. 2.7.5) -- Installing `v8` via homebrew: `brew install v8` -- Installing the `libv8` gem using a specific version and v8 flag: - `gem install libv8 -v '3.16.14.19' -- --with-system-v8` -- Assigning configuration options, as in - [this comment](https://gist.github.com/fernandoaleman/868b64cd60ab2d51ab24e7bf384da1ca#gistcomment-3114668). - -
+- [Getting Started](docs/getting_started.md) - Setup, running locally, and deploying +- [Authoring Articles](docs/authoring_articles.md) - Writing blog posts, adding authors, and enabling comments +- [Authoring Podcasts](docs/authoring_podcasts.md) - Adding podcast episodes ## License @@ -33,177 +15,6 @@ The code in this repository is released under the MIT license. The contents of the blog itself (ie: the contents of the `_posts` directory) are released under +[Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). -## Running the OSS Site / Blog locally - -Running `rake serve` will _not_ generate category pages. They take a _long_ time -to generate. No one wants that when working on the site. - -``` - bundle exec rake serve -``` - -Categories are generated when the ENV var `PRODUCTION` = `"YES"`. - -## Deploying - -- Circle automatically deploys to GitHub Pages when new commits are pushed to - the `source` branch. -- If you need to trigger a deploy locally, the `rake deploy` command is - available. -- See the `Rakefile` for details on how builds/deploys are done. -- Note that the `main` branch does not build on Circle, due to all deploy - commits being prefixed with `[skip ci]`. - -## Adding an Author - -Authors are key-value stored, so you will need to give yourself a key inside -[\_config.yml](_config.yml) - for example: - -```yaml -joey: - name: Joey Aghion - github: joeyAghion - twitter: joeyAghion - site: http://joey.aghion.com -``` - -Everything but name is optional. - -## Authoring an Article - -Note: we now have some templates to help get you started writing a blog post. -Check out the [`Post-Templates` directory](Post-Templates). - -TLDR _To generate a new post, create a new file in the `_posts` directory. Be -sure to add your name as the author of the post and include several categories -to file the post under. Here is a sample header YAML:_ - -Note: categories are aggregated from the individual posts, so adding one is as -easy as adding it to your post! - -```yaml ---- -layout: post -title: "Responsive Layouts with CSS3" -date: 2012-01-17 11:03 -comments: true -author: Matt McNierney -github-url: https://www.github.com/mmcnierney14 -twitter-url: http://twitter.com/mmcnierney -blog-url: http://mattmcnierney.wordpress.com -categories: [Design, CSS, HTML5] ---- -``` - -More info can be found in the [Jekyll docs](http://jekyllrb.com/docs/posts/). - -When you have authored an article, `git add` and `git commit` it, then push to a -named branch with `git push origin [branch]`, and create a pull request to the -`source` branch, it will be deployed to the site by travis when merged. - -After you have authored an article, consider re-generating the related articles -data, so that we can surface other articles related to the one you just added. -See **Generating related articles** section below. - -## Enabling Comments - -Comments for articles are managed with -[Issues](https://github.com/artsy/artsy.github.io/issues) in this GitHub -repository. - -#### [Create an issue](https://github.com/artsy/artsy.github.io/issues/new) for the article - -Quote the opening paragraph(s) of the post as the body of the issue, and name it -something like "Comments: My Fantastic New Post". - -#### Add the `Comment Thread` label to the issue - -#### Attach the issue to your article - -Copy the created issue ID; add it to the frontmatter YAML of your post, as the -`comment_id` attribute: - -`comment_id: 1234` - -## After Deploying an Article - -Every article on our blog needs one more thing: a snappy tweet! You can ask Ash -or Orta to do this for you, but you're also welcome to log into the -[@ArtsyOpenSource](https://twitter.com/ArtsyOpenSource) twitter account and -tweet yourself (credentials are in the Engineering 1Password vault). Tweets -usually follow the following format: - -``` -[pithy observation] [description of problem] [@ the article author's twitter handle] - -📝 [link to blog post] -💻 [link to GitHub repo, if applicable] -📷 [attach a screenshot of the first few paragraphs of the post] -``` - -We attach screenshots of the post because tweets with images get more traction. -But! Images aren't accessible to screen readers, so make sure to use the -twitter.com web interface and add a description to the image when posting: - -> Screenshot of the title and first two paragraphs of the linked-to blog post. - -You can look at previous tweets from our account to get a feel for these. If -you'd like help, just ask in Slack. - -## Authoring a Podcast Episode - -To add a new episode of the podcast, -[configure](https://github.com/aws/aws-sdk-ruby#configuration) your local AWS -environment. The easiest is in environment variables stored in `~/.zshrc` or -equivalent. - -``` -export AWS_ACCESS_KEY_ID= -export AWS_SECRET_ACCESS_KEY= -``` - -After you have set up the environment, run the following rake task. - -```sh -rake podcast:new_episode /path/to/local/mp3 -``` - -This will add required YAML to `_config.yml`. You'll need to fill in some other -fields manually; when finished it'll look like this: - -```yaml -- title: Name of your episode - date: (generated by Rake task) - description: A paragraph-long description of the episode. - podcast_url: (generated by Rake task) - file_byte_length: (generated by Rake task) - duration: (generated by Rake task) -``` - -## Generating related articles - -Generating the content for the "related articles" section at the bottom of an -article is an offline & manual process that makes use of our staging vector -database. - -Any developer can run this at any time and commit the resulting changes to -`related-articles.json`. - -There are a few simple prerequisite steps required for this task specifically: - -1. `gem install foreman`, if you haven't already. - -2. `cp .env.example .env`, if you haven't already. - -3. Connect to the staging VPN in order to access the staging instance of - Weaviate, our vector database. - -After that it is just: - -```sh -foreman run bundle exec rake related_articles -``` - ## About Artsy diff --git a/docs/authoring_articles.md b/docs/authoring_articles.md new file mode 100644 index 0000000000..5dbee9a855 --- /dev/null +++ b/docs/authoring_articles.md @@ -0,0 +1,106 @@ +# Authoring Articles + +- [Authoring Articles](#authoring-articles) + - [1. Adding an Author](#1-adding-an-author) + - [2. Creating a Post](#2-creating-a-post) + - [3. Submitting Your Post](#3-submitting-your-post) + - [4. Enabling Comments](#4-enabling-comments) + - [5. After Deploying](#5-after-deploying) + - [6. Generating Related Articles](#6-generating-related-articles) + +--- + +## 1. Adding an Author + +Authors are key-value stored in [\_config.yml](../_config.yml). Add yourself with a key: + +```yaml +joey: + name: Joey Aghion + github: joeyAghion + twitter: joeyAghion + site: http://joey.aghion.com +``` + +Everything but name is optional. + +## 2. Creating a Post + +Create a new file in the `_posts` directory. Templates are available in the [`Post-Templates`](../Post-Templates) directory. + +Include this YAML header: + +```yaml +--- +layout: post +title: "Responsive Layouts with CSS3" +date: 2012-01-17 11:03 +comments: true +author: Matt McNierney +github-url: https://www.github.com/mmcnierney14 +twitter-url: http://twitter.com/mmcnierney +blog-url: http://mattmcnierney.wordpress.com +categories: [Design, CSS, HTML5] +--- +``` + +Categories are aggregated from individual posts - adding a new one is as easy as including it in your post. + +More info in the [Jekyll docs](http://jekyllrb.com/docs/posts/). + +## 3. Submitting Your Post + +```bash +git add . +git commit -m "Add blog post: Your Title" +git push origin your-branch +``` + +Create a PR to the `source` branch. It will be deployed when merged. + +After authoring, consider [regenerating related articles](#6-generating-related-articles). + +## 4. Enabling Comments + + _(optional)_ +Comments are managed with [GitHub Issues](https://github.com/artsy/artsy.github.io/issues). + +1. [Create an issue](https://github.com/artsy/artsy.github.io/issues/new) - quote the opening paragraph(s) and name it "Comments: My Fantastic New Post" +2. Add the `Comment Thread` label +3. Add `comment_id: ` to your post's front matter + +## 5. After Deploying + +Tweet from [@ArtsyOpenSource](https://twitter.com/ArtsyOpenSource) (credentials in Engineering 1Password vault): + +``` +[pithy observation] [description of problem] [@ author's twitter] + +[link to blog post] +[link to GitHub repo, if applicable] +[attach a screenshot of the first few paragraphs] +``` + +Add image description for accessibility: + +> Screenshot of the title and first two paragraphs of the linked-to blog post. + +## 6. Generating Related Articles + +_(optional)_ + +The "related articles" section is generated offline using our staging vector database. + +**Prerequisites** + +1. Install foreman: `gem install foreman` +2. Copy environment file: `cp .env.example .env` +3. Connect to the staging VPN to access Weaviate (our vector database) + +**Generate** + +```sh +foreman run bundle exec rake related_articles +``` + +Commit the resulting changes to `related-articles.json`. diff --git a/docs/authoring_podcasts.md b/docs/authoring_podcasts.md new file mode 100644 index 0000000000..28dd8442ce --- /dev/null +++ b/docs/authoring_podcasts.md @@ -0,0 +1,29 @@ +# Authoring Podcast Episodes + +## Setup + +[Configure](https://github.com/aws/aws-sdk-ruby#configuration) your local AWS environment. Add to `~/.zshrc` or equivalent: + +``` +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +``` + +## Adding an Episode + +Run: + +```sh +rake podcast:new_episode /path/to/local/mp3 +``` + +This adds required YAML to `_config.yml`. Fill in the remaining fields: + +```yaml +- title: Name of your episode + date: (generated by Rake task) + description: A paragraph-long description of the episode. + podcast_url: (generated by Rake task) + file_byte_length: (generated by Rake task) + duration: (generated by Rake task) +``` diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000000..28fb017d49 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,44 @@ +# Getting Started + +## Setup + +``` +git clone git@github.com:artsy/artsy.github.io.git +cd artsy.github.io +bundle +bundle exec rake bootstrap +bundle exec rake build +``` + +
+Common Issues + +### Issues installing `therubyracer` and/or `v8` dependencies + +Some combination of the following might help: + +- Make sure you have a ruby version that works (e.g. 2.7.5) +- Installing `v8` via homebrew: `brew install v8` +- Installing the `libv8` gem using a specific version and v8 flag: + `gem install libv8 -v '3.16.14.19' -- --with-system-v8` +- Assigning configuration options, as in + [this comment](https://gist.github.com/fernandoaleman/868b64cd60ab2d51ab24e7bf384da1ca#gistcomment-3114668). + +
+ +## Running Locally + +Running `rake serve` will _not_ generate category pages. They take a _long_ time to generate. + +``` +bundle exec rake serve +``` + +Categories are generated when the ENV var `PRODUCTION` = `"YES"`. + +## Deploying + +- Circle automatically deploys to GitHub Pages when new commits are pushed to the `source` branch. +- If you need to trigger a deploy locally, the `rake deploy` command is available. +- See the `Rakefile` for details on how builds/deploys are done. +- Note that the `main` branch does not build on Circle, due to all deploy commits being prefixed with `[skip ci]`.