A Documentation serie

Dev Guides

Tue Jul 07 2020
avatar
Xavier Bruhiere
linkedintwitterfacebook
intro picture

Various guides on using this kind-of-portfolio-framework, if you wish to maintain your own copy. Learn how to generate its RSS, write posts, and more...

Follow along

# Pre-build scripts

RSS items and build information are generated by script prior to compiling the website itself.

Generate build metas

Running npm run metas or node ./etc/generate-build.js will dynamically look at the environment and output in ./config/build.json the following data:

{
  "ts": "2020-07-08T08:48:29.956Z",
  "commit": "538300e",
  "nodejs": "v13.13.0",
  "platform": "darwin-x64"
}

Subsequentely this data is loaded in the project ./config/index.js and can be used/imported. For example hover the top left domain on any page and you will see the build hash.

Generate RSS Feed

RSS is having a renewed interest so the project supports it. It works by looking at the last articles available and generating the standard XML for reader consumption.

Note: This step is included in the build process, like the _metas_ script.
  • Customize number of posts delivered in ./config/index.js (atom_items, default to 10)
  • Run npm run rss or babel-node ./etc/generate-rss-feed.js

# Write a post

Warning: Work in progress. The API is far from stable and I am experimenting with different layouts, as well as adding useful components for technical writing.

Posts are powered by Mdx and mix react components with usual markdown. Utilimately the goal is to not depart from the effectiveness of Markdown, while still allowing reach content interactions.

Disclaimer: That may disappoint `noscript` advocates and I acknowledge there arecompelling reasons to go this route. I just don't care and hope to build rich and fun experiences, as long as security and performance are not compromised.

So create a new MDX file under pages/essays, like my-post.mdx. To kickstart the boilerplate you can copy the template like so: cp pages/essays/_dev/minimal.mdx pages/essays/my-post.mdx.

Or use (again) the generator ./etc/write/index.js draft --help.

Then add an entry in config/posts.json to reference the post in your the overview.

…
{
  "date": "May 23, 2019",
  "title": "The over-engineered todolist",
  "link": "/essays/todolist",
  "draft": true,
  "tags": [
    "serie",
    "distributed",
    "big-data"
  ],
  "reading_time": "1h",
  "tldr": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.",
  "publisher": "Me"
},
…

# Custonise style

Sass files is split between:

  • Component-scoped sass files, sitting next to their React counterpart/file.
  • The /styles folder, meant to define global settings, common helpers and useful components.

Credits: Architecture for a Sass project

# Optimize images

brew install imagemagick
convert -geometry 578x src/image1.png out/image1.png
open -a ImageOptim kpler.jpg




#docs#guide#tools

Read Next

Modern Go Development

The Go language indisputably generates lot of discussions. Bjarne Stroustrup famously said: There are only two kinds of languages: the ones people complain about and the ones nobody uses