Merge pull request #138 from infinum/develop

Version 6 deploy

Author: dingo-d

.github/workflows/documentation.yml

@@ -2,23 +2,32 @@ name: documentation
 
 on:
   push:
+    paths-ignore:
+      - '**.md'
     branches:
       - main
+      - develop
   # Allow manually triggering the workflow.
   workflow_dispatch:
 
 defaults:
   run:
     working-directory: ./website
 
+# Cancels all previous workflow runs for the same branch that have not yet completed.
+concurrency:
+  # The concurrency group contains the workflow name and the branch name.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   checks:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
-          node-version: '14.x'
+          node-version: '16.x'
       - name: Test Build
         run: |
           if [ -e yarn.lock ]; then
@@ -31,12 +40,14 @@ jobs:
             yarn run build
 
   gh-release:
+    name: Release docs
+    if: ${{ github.ref == 'refs/heads/main' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
-          node-version: '14.x'
+          node-version: '16.x'
       - uses: webfactory/ssh-agent@v0.5.0
         with:
           ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}

.gitignore

@@ -1,4 +1,6 @@
 .DS_Store
+.idea
+.vscode
 
 node_modules
 

README.md

@@ -1,6 +1,5 @@
-<p align="center">
-	<img alt="Eightshift Frontend Libs" src="https://repository-images.githubusercontent.com/236449101/77ca190e-d3c9-41a3-9f76-2cc04a6bab62"/>
-</p>
+![image](https://user-images.githubusercontent.com/77000136/146529640-fb4a0dc8-af62-4249-ae05-fa3286b46a22.png#gh-light-mode-only)
+![image](https://user-images.githubusercontent.com/77000136/146529660-5a68acb5-e6a3-4634-8603-5c03e52779ea.png#gh-dark-mode-only)
 
 [![GitHub tag](https://img.shields.io/github/tag/infinum/eightshift-docs.svg?style=for-the-badge)](https://github.com/infinum/eightshift-docs)
 [![GitHub stars](https://img.shields.io/github/stars/infinum/eightshift-docs.svg?style=for-the-badge&label=Stars)](https://github.com/infinum/eightshift-docs/)

website/blog/2022-01-20-initial-setup.md

@@ -0,0 +1,60 @@
+---
+title: Initial setup and first steps
+description: This blog post describes how to set up Eightshift Boilerplate theme, and covers some of the most common issues that may occur
+slug: initial-setup
+authors: iobrado
+tags: [eightshift, boilerplate, setup]
+hide_table_of_contents: false
+---
+As is often the case when trying out something new, you might encounter some hiccups. You're trying out our Eightshift Boilerplate, but can't get it to work? Worry not, we'll go through the setup and the most common issues that may occur.
+
+<!--truncate-->
+If you haven't already, be sure to read our official [Eightshift Docs](https://infinum.github.io/eightshift-docs/docs/welcome).
+
+### Setup
+
+To create Eightshift theme, navigate to `wp-content/themes` in your project and type the following in the terminal:
+
+```bash
+npx create-wp-project
+```
+
+Just follow the instructions and wait for the theme to download.
+
+![Setup - initial prompt](/img/blog/setup-1.png)
+
+OK, you went through the process, filled out all required information, but the theme still isn't working. There are a few more instructions in the terminal on what to do next, but you may have skipped them. While the principle **"6 hours of debugging can save you 5 minutes of reading documentation"** is fun, sometimes it's just not worth it. Here's what you should do:
+
+- run `wp theme activate your-theme-name` to activate your new theme
+- navigate to `wp-content/themes/your-theme-name`
+- try running `wp boilerplate --help` to check if our WP CLI boilerplate commands work
+- for easiest initial setup, run `wp boilerplate setup_theme`
+- `npm start` should trigger automatically with the previous command. If it doesn't, you can run it manually to finish the theme build process
+
+![Setup - instructions](/img/blog/setup-2.png)
+
+Congratulations, you've set up your Eightshift theme!
+
+### Getting to know Eightshift dev tools
+
+After successfully setting up the theme and going through files, you'll notice this file structure is quite different from traditional WordPress themes and you may think to yourself: "Oh wow, what did I get myself into?"
+
+While it may look scary and confusing at first, once you get used to the structure, you'll see the benefits. More about that will be covered in future posts, where we'll walk you through some basics of developing with Eightshift Boilerplate.
+
+You may want to try a few of our WP CLI commands to add another component, block, or service class. Running `wp boilerplate --help` will give you a list of commands and their short description. If you need even more details about a specific command, you can type, e.g. `wp boilerplate create_post_type --help`
+
+The final tip in this post is related to troubleshooting. Maybe you tried to add a new class or a new feature to one of the existing blocks. And now the site has crashed. In tech support, the number 1 question is **"Have you tried turning it off and on again?"**. In our case, the number 1 question is:
+
+> Have you tried `composer dump-autoload` and re-running `npm start`?
+
+### What's next in store?
+
+That's all for this post. In future posts we'll go through some more how-to examples like:
+- the difference between components and blocks
+- downloading components and blocks from our Storybook with WP-CLI
+- adding new features to components and blocks
+- adding custom fonts to your project
+- adding custom queries which we'll use in one of our blocks
+- and many more...
+
+So stay tuned.

website/blog/2022-01-21-components-and-blocks.md

@@ -0,0 +1,62 @@
+---
+title: Components and blocks
+description: Explanation of the difference between components and blocks on a practical example
+slug: components-and-blocks
+authors: iobrado
+tags: [eightshift, boilerplate, components, blocks]
+hide_table_of_contents: false
+---
+In this blog post, we'll give you a practical explanation about the difference between components and blocks. For a truly in-depth explanation about components and blocks, you can refer to [our documentation](https://infinum.github.io/eightshift-docs/docs/basics/blocks). A more specific explanation about using components in a block can be found in the [Component in a Block](https://infinum.github.io/eightshift-docs/docs/basics/blocks-component-in-block/) section.
+
+<!--truncate-->
+One of the things that is really confusing to newcomers is the difference between components and blocks. Let's break it all down.
+
+### Component
+
+> A component is like a blank slate, a template without context.
+
+It doesn't know or even care for what it will be used. Can you combine multiple simple components into one complex component? Absolutely! That's exactly what we'll do in the following example. 
+
+Let's say we have a component that consists of an image and a heading. Image and heading are two simple components that come with the theme out-of-the-box.
+
+Here are a few examples of how this new component can be used:
+- displaying a post
+- displaying a user or an author
+- displaying a photo with the photographer's name
+- and many more...
+
+As you can already see, there are many ways you can use this component. What helps expand the usability of this component even more are `attributes`. Let's say we have the following attributes:
+- `imagePosition` - left, right, top, bottom
+- `imageShape` - rectangular, circular
+- `imageWidth` - 25%, 50%, 75%
+- `headingColor` - black, blue, red
+- `headingSize` - small, medium, large
+
+These attributes give you the option to modify the look of the component, so this specific component can be used for the following:
+
+- **related posts** - rectangular image on the left side, 25% image width, heading takes up the remaining 75%, medium heading colored in blue
+- **user avatar** - circular image on the left side, 25% image width, small heading colored in black
+- **photo of the day** - rectangular image on the right side which takes 75% width and photographer's name is written in medium blue text
+- **featured posts** - rectangular image on top, large heading in red color
+
+![Component with different attributes](/img/blog/components.png)
+
+You can even add conditional logic to your options, e.g. to have the option for `imageWidth` visible only when `imagePosition` is set to left or right. And when `imagePosition` is set to top or bottom, it defaults to 100% width.
+
+### Block
+
+So, what about blocks? Blocks can consist of one or more components and, most importantly, allow you to use them in the editor. Technically, blocks can consist of zero components, but we encourage you to build blocks from components because that increases the reusability.
+
+> Blocks give context to the components.
+
+Now that we have our component - let's call it `card-simple` - we can use it in a `Featured Posts` block. In **component's** `manifest.json`, we've already defined how we want it to look by setting some defaults. When using this component in our block, we can override some attributes in **block's** `manifest.json`. Since it will be used for displaying featured posts, we can define that `imagePosition` should be set to **top**.
+
+After defining how we want our component to look while displaying featured posts, we need another attribute which will allow us to choose which posts to display in our block.
+
+To do that, we'll add a new attribute called `featuredPosts` which will define which posts will be displayed in our block. For each selected post, another `card-simple` component is added, and featured image and post title are dynamically added to its image and heading components. More about the query logic and adding new options in a block will be covered in a future post.
+
+You may be wondering, can you have a block that allows you to use all options of the `card-simple` component? Of course! You can create a block that allows you to set all available options in the editor and manually add content to the image and heading. There are also block variations, which allow you to set up predefined attributes for a block. More about setting up block variations may be covered in one of the future posts.
+
+### Conclusion
+
+Hopefully, these examples helped you get a better understanding of the difference between components and blocks. It may take a bit more time or practical use to understand the difference and reasoning behind it. Our next post will walk you through downloading one of our components and blocks with WP CLI and modifying it.

website/blog/authors.yml

@@ -0,0 +1,3 @@
+iobrado:
+  name: Igor Obradović
+  title: WordPress Engineer @ Infinum

website/docs/basics/backend.md

@@ -1,6 +1,6 @@
 ---
 id: backend
-title: Backend
+title: General
 ---
 
 [![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs)

website/docs/basics/basics.md renamed to website/docs/basics/basics-intro.md

@@ -1,5 +1,5 @@
 ---
-id: basics
+id: basics-intro
 title: Basics
 ---
 

website/docs/basics/blocks-component-in-block.md

@@ -80,11 +80,11 @@ For more details please check our helpers sections for [JavaScript](helpers-java
 
 By defining components key in the block registration phase we are drilling down from block to the last component and setting up attribute names according to your setup. In order for everything to work, we had to add/change prefixes to each component attribute in relation to where this attribute is used in the dependency tree. It is not so hard as it sounds so let us show you some graphical examples:
 
-![Attributes 1](/eightshift-docs/img/docs/attributes-1.png)
+![Attributes 1](/img/docs/attributes-1.png)
 
-![Attributes 2](/eightshift-docs/img/docs/attributes-2.png)
+![Attributes 2](/img/docs/attributes-2.png)
 
-![Attributes 3](/eightshift-docs/img/docs/attributes-3.png)
+![Attributes 3](/img/docs/attributes-3.png)
 
 ### I want to use one heading component in my block.
 

website/docs/basics/blocks-faq.md

@@ -73,7 +73,7 @@ wp boilerplate use_component --help
 
 It depends. You can't use things from the blocks folder like `components`, `custom`, `variations`, `wrapper`, etc. They are meant to be copied to your project, styled, and changed depending on your project's needs.
 
-You can move things from a block to your project using the commands described in [this chapter](blocks-intro#how-can-i-use-your-pre-made-blocks).
+You can move things from a block to your project using the commands described [above](#how-can-i-use-your-pre-made-blocks).
 
 ### I want to change attributes on inner blocks. How do I do it?