xebia / essentials

Static site generator for the Xebia Essentials cards

Website | Api | iOS source | Android source | Xebia | Blog

Xebia Essentials static site generator

This repository contains the static site generator for the Xebia Essentials, along with all the cards' content and metadata. Each page contains YAML front matter, two optional markdown sections for the front and backsites of the printed cards followed by a final markdown section that will be converted into the corresponding web page.

This results in the following layout:

---
metadata
---
front
---
back
---
webpage

Configuration is done through Gridsome's gridsome.config.js and gridsome.server.js.

Pull requests are more than welcome, see the open issues!

Licence

The content is lienced under CC BY-NC 4.0, with the exception of the images and text-content of the cards for which the copyright is maintained.

Local development

Dependencies

The project expects you to have NodeJS (12) and NPM 6 (lockfile v1) installed.

Install all dependencies through

npm install

Build & Serve

To locally serve the statically generated site at https://localhost:8080, and automatically rebuild when any file is changed, run from the project root directory:

npm run develop

GraphQL Playground is at https://localhost:8080/___explore.

Build the static site using

npm run build

Deploying to essentials.xebia.com

TBD

essentials's Issues

Make category colour configurable

Should be an entry under _config.yml

Write a blog series

I suggest we write a four part blog series:

1. General announcement of v2.0 of the essentials cards, and explanation of the new categories and content. Suggested author(s) being @barend and perhaps Lotte.
2. Outline of the new statically generated site, Jekyll, and the exposed API. Written by myself, @jbnicolai
3. iOS app, by @lammertw
4. Android app, by @MarcGrol

Automatically generate the list for TOC

Currently the /cards/ page consist of a static list of all cards.

It would be nicer if this list was generated at build time.

Move the Android project into a separate repository

We have both the website and the Android code in here for historic reasons, but it's impractical and confusing. Best split that off, as has already happened with the iOS code.

Buy button on card page not positioned well on small screens

During testing of the new release of the iOS version of the essentials an issue was discovered.

The buy buttons's margin is too small. This would look way better with a little bit of margin. surrounding the buy button.

Reported by @agemooij @cvandenthillart

Fix bug with api.json being written to source rather than destination

Currently the generated api file is written to source/api.json, picked up by jekyll as an input file and copied over to destination/.

This is to work around a bug where writing to destionation/ would be overwritten by jekylls own cleaning when building.

Integrate new product photos

Use the new shots hosted on the internal egnyte where appropriate.

Suggestions:

• 724 on the TOC page.
• 782 or 792 for the books page
• ??? for the social media preview image
• ??? update the index page's image?

Include category colour in api.json

Automated releasing

Create a script to automatically release to essentials.xebia.com

Card Suggestion: No long-lived branches

Card suggestion: Stop starting - Start finishing

A well known quote for most, but not truly lived by most development teams.
Usually of the 10 Backlog Items in the Sprint, 8 are in progress at the same, resulting in a lot of undone work the end.

Focus of finishing something before you start something new. Practices like swarming and mob-programming can help retain focus on the (limited) work in progress

Tip: Work with WIP limits to enforce this practice

Alignment of main text differs

The placement of the main text on the cards differs from card to card. On most cards the text us aligned at the top. Others start a 'line' lower.
Examples are the "Develop for Security" and "Share the Design" cards.

Meta tag for smart app banner does need a protocol part

Just came to the conclusion that the smart app banner does indeed need the protocol part.

Code in question is here:

essentials/_includes/meta-tags.html

Line 18 in f953518

<meta name="apple-itunes-app" content="app-id=883300245, app-argument={{site.url}}{{page.url}}">

web: "Related Cards" inconsistencies

How to handle "related card" references?
Should we specify them in their own section, in a single-line entry (as in hurt-often, poutsma-principle), or in multiple entries (as in acceptance-criteria) ?

Some other inconsistencies:

• done.md: "Related cards" is not written in the right place, we should also replace ## Code Review by ### References
• two-minute-rule.md: related cards have no link

Layout issue with pages that contain wide code sections on mobile devices

Certain web pages cause layout issues when rendered on the mobile device.

Example: "Comment with care"

@cvandenthillart found this bug.

Feature suggestion: link to github with specific URL per card

See a random google web starter kit page's submit feedback link on the top-right of the page. It will allow users to create an issue and mentions the corresponding card.

Dead hyperlink in no-test-no-bugfix

The outgoing link in the references section is dead.

Possible alternatives:

• http://nparc.cisti-icist.nrc-cnrc.gc.ca/npsi/ctrl?action=rtdoc&an=5763742&article=0&lang=en
• http://swerl.tudelft.nl/twiki/pub/Main/PastAndCurrentMScProjects/Thesis_Dennis_de_Bode.pdf

(Submitted via email by Daniela Buricescu)

Create api.json

Generate an 'api.json' file listing the tiltles, types, front and back of each card.

Freedback for: /two-minute-rule.html

I feel like two minutes is too low a bar.