artsy / artsy.github.io Goto Github PK

The Artsy Engineering Open-Source Developers Blog

License: MIT License

HTML 9.49% JavaScript 2.20% Ruby 4.42% SCSS 83.89%

artsy jekyll blog

artsy.github.io's Introduction

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.

Setup

git clone [email protected]: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.

License

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.

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 - for example:

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.

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!

---
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.

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 in this GitHub repository.

Create an issue 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 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 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.

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:

- 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:

gem install foreman, if you haven't already.
cp .env.example .env, if you haven't already.
Connect to the staging VPN in order to access the staging instance of Weaviate, our vector database.

After that it is just:

foreman run bundle exec rake related_articles

About Artsy

This project is the work of engineers at Artsy, the world's leading and largest online art marketplace and platform for discovering art. One of our core Engineering Principles is being Open Source by Default which means we strive to share as many details of our work as possible.

You can learn more about this work from our blog and by following @ArtsyOpenSource or explore our public data by checking out our API. If you're interested in a career at Artsy, read through our job postings!

artsy.github.io's People

Contributors

Stargazers

Watchers

Forkers

mmcnierney14 speednoisemovement orta fancyremarker switz jessclee alexanderfabry afeld imclab admix randomstuffs22 parikhutsav beelah jakesylvestre noblinto pnoble04 ashfurrow mtv4410 craigspaeth anipetrov ilyakava esttorhe shaneowens 1aurabrown igzcarlosmanzanas sweir27 broskoski sarahscott aureliafg starsirius zamiang dasburo stormpig dblock saniul yzakizon mzikherman stahwa mthoericht ashkan18 jtotoole neilkimmett transformersprimeabcxyz mesakennedy girasquid mariusc petemill omosofe mwfire snek-byte acjay sheppard199 leighannskeen yathoroo havilee marwanlingga pedrovereza whaletail universal-it-systems cogell hboon haroenv klop vijaytholpadi codetrail kanaabe f4lconxx ladyshock nickweinberg gramrattan cavvia erikdstock wrgoldstein zeno-vg haujason animay thepro-dot-xyz alvincjin sarkartanzil dolbyover eliperkins davimacedo noreta eessex arvidpoon krausefx felipesabino bedjan sagar-kalra janickid barexam rezanbda imgbotapp italoadler rumberg myux shubhampachori12110095 markseltenrijch harikrishnannb hsp16

artsy.github.io's Issues

Upgrade Jekyll

Visual fix

Increase line-height on intro paragraph to 42px:

Remove "Last Update here..."

Links in the footer are not clickable

Chrome:

Safari:

Analytics broken

Google analytics stopped working around 8/11, presumably with the port to Jekyll.

Interestingly, it's still recording a few visits (1-5/day).

Category links don't work

Clicking on a category link on an article leads to nothing – it's href is the category name. So clicking eigen tries to navigate to //eigen/.

We lost disqus?

No more comments on posts :(

Date on browser scaling

The date here should be left aligned with the body para (it gets pushed to the bottom at a certain breakpoint, but currently stays out to the right).

Author pages

Could be an expansion on the categories plugin?

Create blog post on debugger dancing

In this case regarding the issue outlined here artsy/eigen#203.

names to posts?

it'd be nice to know who wrote which post.

Update the ARAnalytics DSL blog post now our use cases are OSS

Can provide direct links to real world use-cases

Inconsistent padding on projects

Viewing in safari, padding top should be what the bottom padding is now.

Site search redirects to a google search for the term

Enter a query in the search input box.
See the results for your search on a google custom search page
…and then instantly be redirected to an internet-wide google search for that term

Background color missing at top of page

Currently the body background-color is set to white which means if I'm poking around the header it looks like this:

Would be nicer if if the area "above the body" background-color #dbffff so it looked like this:

(Same thing if I pull left and right in my browser but much less important since it's much less likely that the user will see it.)

Get rid of this margin-top when no there is no project image

The first link in README file is broken.

The first link (which should go to the blog) is broken and gives 404.
To fix it:
<a href="http://artsy.github.com">http://artsy.github.com</a>

Jumping to a section of the overview takes you below the top

Clicking on one of the nav items on the side should take you to the top of the section (currently its a little below the top which seems confusing).

Jumping to a section should result in the top of that section being aligned with the top of the nav, like so:

Also would be nice if we could do a smooth scroll to that section rather than a jump.

Inline code blocks are too big

Add instructions to README for adding a new author

Notorious BUG – The Unbugged sessions Part 2.

Create a post about the malloc_history fun @1aurabrown and I once had in Slack.

Open source sub head

Let's either hide this, or if possible, pull in the latest tweet from the open source twitter.

Comments section styling

Any way we could simplify this by hiding the logo / all links at the bottom, getting rid of the redundant comments header, and using garamond instead of their typefaces?

New Design

Comps for the new Open Source page and Engineering Team Blog. It would be great to walk through this with whoever picks it up to make sure that it's clear.

Mobile version here:

cc: @orta @robertlenne

Switch to generating the Open Source Projects from a data file

That way we can have an Artsy OSS list thats not in HTML, and the open source page can get updated from that. It's a lot of effort to update ATM.

Remove underscore.js

Looks like it's only used as an each function 4-5 times, not worth a 16kb download.

Graphics not retina

Comments and Tweet button do not load on https

Visit https://artsy.github.io/blog/2014/10/23/how-we-customized-google-site-search-at-artsy/
See

Create a print stylesheet

Re: https://twitter.com/jclwilson/status/629324277754523649

Search has no loading indicator

It takes a reasonable bit of time, and everything looks a tad broke.

broken images on how artsy uses github

See: http://artsy.github.io/blog/2012/01/29/how-art-dot-sy-uses-github-to-build-art-dot-sy

e.g. http://artsy.github.io/blog/2012/01/29/how-art-dot-sy-uses-github-to-build-art-dot-sy/Targeted%20Pull%20Request
meaning: /images/2012-01-29-how-art-dot-sy-uses-github-to-build-art-dot-sy/github-pull-request.png

Perhaps was a part of the jekyll migration?

Fix PRs from forks

Pros from forks (example) don't build correctly since they don't have access to Travis' secure environment variables. We don't actually need them except for builds on master, which are deployed, so we should fix our CI setup to not rely on them on non-master builds.