chore: pre-commit linting (#54)

* chore: script to lint mdx files by parsing it

To implement auto translation, we need to create a script to
separate some nodes such as import statement and code block using
`remark` package. For that script to work, the mdx files need
to be parseable by `remark`. Therefore, we need to check before commit
whether all mdx files are parseable.

* fix: fix mdx syntax errors

There are 4 common errors:
1. Passing a JSX element as prop without curly braces.
2. `<a>` tag not started in new line
3. Whitespace expression `{" "}` right after `</a>` on the same line.
4. Whitespaces before JSX component, import statement, paragraph, etc.
   It can be fixed by using prettier.

Also, I remove unused `alt` prop that's passed to `IfcImage` component.

* chore: run yarn lint before every commit

* add prettier

* chore: format using prettier

By formatting `.mdx` files with prettier, it will minimize mdx
parsing error that being caught by the linter.

This commit also fix:
1. Syntax error after being formatted
2. Non-syntax error that make the formatting unstable (previous
   to next formatting have different result when there is no change).

TODO:
1. Create MDX authoring guidelines to prevent and fix syntax errors
   and formatting unstability.

* chore: runt format linter before every commit

* Provide common solutions for MDX parsing errors and volatile formatting

* format with prettier

* format staged files instead of --list-different

Turns out `prettier --list-different` will always erroring out in
Windows if the end of line character is converted from Linux style to
Windows style by git when executing git checkout, pull, etc.

So, I think it's better to automatically format staged files before
every commit.

* remove formatting first guideline in MDX.md

* change prettier printWidth for .md and .mdx files.

The whitespace `{" "}` JavaScript expression will be treated as
text by Deepl. Sometimes, it will be relocated (e.g. in Japanese)
from the end of line to the middle of line which is not desired.

By setting the printWidth to Infinity, the text will not be wrapped
to next line, so there is no need for the whitespace `{" "}` expression.

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+yarn pretty-quick --staged && yarn lint

.prettierignore

@@ -0,0 +1,23 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+i18n
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+deepl/deepl.json

MDX.md

@@ -0,0 +1,80 @@
+# MDX Common Errors
+
+The MDX compiler is not that smart. So, we need to make sure that we write MDX in a way that compiler can understand.
+
+Few things you have to keep in mind:
+
+1.  `<a>` opening tag must be placed on the start of a line without any character before it except whitespaces.
+
+```jsx
+❌
+
+Click this <a href="https://ifcjs.github.io/info">link{" "}</a>
+to IFC.js website.
+
+✔
+
+Click this{" "}
+<a href="https://ifcjs.github.io/info">link </a>
+to IFC.js website.
+```
+
+2.  `</a>` closing tag must not be followed by Javascript expression (encapsulated by `{}` such as `{" "}`).
+
+```jsx
+❌
+
+<a href="https://ifcjs.github.io/info">Link</a>{" "}
+to IFC.js website.
+
+✔
+
+<a href="https://ifcjs.github.io/info">Link{" "}</a>
+to IFC.js website.
+```
+
+3.  JSX element is a Javascript expression. Therefore, if you want to pass a JSX element as a prop of another JSX component, you must wrap it with `{}`.
+
+```jsx
+❌
+
+<IfcImage image=<img src="..." alt=".."></img>></IfcImage>
+
+✔
+
+<IfcImage image={<img src="..." alt=".."></img>}></IfcImage>
+```
+
+4.  Unnecessary whitespaces at the beginning of a line. Try formatting the documents to solve this. Run:
+
+```bash
+yarn format
+```
+
+The MDX formatter is also not that smart. Some characters that are not necessary but acceptable could make the formatting result volatile.
+
+Few things you have to keep in mind:
+
+1.  Do not wrap a prop of JSX component or element with `{}` if it does not need to be a Javascript expression. Example:
+
+```jsx
+❌
+
+<a href={"https://ifcjs.github.io/info"}>Link</a>
+
+✔
+
+<a href="https://ifcjs.github.io/info">Link</a>
+```
+
+After applying above solutions, format your MDX documents. Run:
+
+```bash
+yarn format
+```
+
+Then check the stability. Run:
+
+```bash
+yarn lint:format
+```

README.md

@@ -11,21 +11,21 @@
 
 This repository is the official documentation of [IFC.js](https://github.com/IFCjs). You can visit it live [here](https://ifcjs.github.io/info/). It contains all the information regarding the project, including:
 
-* The motivation behind IFC.js.
+- The motivation behind IFC.js.
 
-* Introduction to all the modules of the library.
+- Introduction to all the modules of the library.
 
-* API reference.
+- API reference.
 
-* Step by step tutorials.
+- Step by step tutorials.
 
-* Informal articles of the authors.
+- Informal articles of the authors.
 
-* Collaboration system and patreon.
+- Collaboration system and patreon.
 
-* Community highlight.
+- Community highlight.
 
-* Link to social networks.
+- Link to social networks.
 
 ## Status
 
@@ -49,26 +49,24 @@ To start the project in another lanaguage, you can use the `--locale` flag:
 
 This project consists of the following folders:
 
-* **docs**: the markdown documents of the documentation.
+- **docs**: the markdown documents of the documentation.
 
-* **blog**: the markdown documents of the blog.
+- **blog**: the markdown documents of the blog.
 
-* **i18n**: the markdown documents of the docs in other languages.
+- **i18n**: the markdown documents of the docs in other languages.
 
-* **src**: react components used in the docs to make cool stuff.
+- **src**: react components used in the docs to make cool stuff.
 
-* **static**: images and icons.
+- **static**: images and icons.
 
 ## Contributing
 
 Want to help out? Great!
 
 These docs use a very simple markdown that makes it super easy to make edits and create new documentation, even if you are not familiar with React. Simply copy markdown documents and they will show up in the documentation with the correct style.
 
-* Feel free to propose new tutorials to the [community](https://discord.gg/FXfyR4XrKT) and submit them here via pull request.
-
-* If you miss any tutorial that is not here, you can make a request in the issues or in our [discord server](https://discord.gg/FXfyR4XrKT).
-
-You can use the pre-made components importing them (check the existing `.jsx` files to find out how) or even create new components to make these docs even cooler. 
+- Feel free to propose new tutorials to the [community](https://discord.gg/FXfyR4XrKT) and submit them here via pull request.
 
+- If you miss any tutorial that is not here, you can make a request in the issues or in our [discord server](https://discord.gg/FXfyR4XrKT).
 
+You can use the pre-made components importing them (check the existing `.jsx` files to find out how) or even create new components to make these docs even cooler.

babel.config.js

@@ -1,3 +1,3 @@
 module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+  presets: [require.resolve("@docusaurus/core/lib/babel/preset")],
 };

blog/2021-07-17-hola.mdx

@@ -6,7 +6,7 @@
   author_url: https://github.com/agviegas
   author_image_url: https://secure.gravatar.com/avatar/9263b9f81d351788e46bc64000c03cb6
   tags: [
-industry, community, project
+    industry, community, project
   ]
 ---
 
@@ -17,25 +17,25 @@ _Who we are and why we do this._
 import { IfcImage } from "../src/components/Image/Image";
 import { IfcCard } from "../src/components/Card/InfoCard";
 
-<IfcImage image=<img src={require('@site/static/img/blog/2021-07-17/Lukas.jpg').default} alt="PC image"></img>
-   alt="PC image" ifcLink="https://www.pexels.com/@goumbik"></IfcImage>
+<IfcImage image={<img src={require("@site/static/img/blog/2021-07-17/Lukas.jpg").default} alt="PC image"></img>} ifcLink="https://www.pexels.com/@goumbik"></IfcImage>
 
 You may have heard about **IFC.js** in recent months. If you are not familiar with the world of software development and BIM, you may be wondering what it is all about.
 
-  🏠
+🏠
 **BIM** (Building Information Modelling) is the new way of working in the construction industry. Instead of drawing plans, three-dimensional models containing the geometry of the building and its information are used. It is very similar to the buildings in [The SIMS](https://www.ea.com/games/the-sims); it saves a lot of money and allows teams to work more efficiently.
 
-  💸
+💸
 However, there is a problem: developing BIM applications is not accesible to everyone, mainly because the necessary technology (**IFC**) is very expensive to implement. This means that until now only a small group of large commercial software houses have had access to the BIM ecosystem.
 
-We believe it's **not fair**. And not only is this not fair to developers who are left out of the market, but it is not fair to customers, who are victims of the predatory pricing of an oligopolistic market. That is why this project exists. 
+We believe it's **not fair**. And not only is this not fair to developers who are left out of the market, but it is not fair to customers, who are victims of the predatory pricing of an oligopolistic market. That is why this project exists.
 
-  <IfcCard>
-  🤝
-Our goal is to enable <b>anyone</b> to create BIM applications.
-  </IfcCard>
+{" "}
+
+<IfcCard>
+  🤝 Our goal is to enable <b>anyone</b> to create BIM applications.
+</IfcCard>
 
 Who are we? A group of developers who want to improve the construction industry in their spare time. The project started in 2021 with [Tom](https://github.com/tomvandig), [Harry](https://github.com/harrycollin) and me and has been growing ever since, with more and more people and companies willing to change the situation in the sector and commit to a **real open BIM**.
 
-  🚀
+🚀
 It doesn't matter if you are a developer, architect, engineer or something else. If you too want to improve the industry, [join us](https://discord.gg/FXfyR4XrKT) and help us make a difference.

blog/2021-07-27-prometheus.mdx

@@ -17,30 +17,29 @@ _Sometimes the only way to get what you need is to do it yourself._
 import { IfcImage } from "../src/components/Image/Image";
 import { IfcCard } from "../src/components/Card/InfoCard";
 
-<IfcImage image=<img src={require('@site/static/img/blog/2021-07-27/prometheus.jpeg').default} alt="PC image"></img>
-   alt="PC image" ifcLink="https://www.museivaticani.va/content/museivaticani/en/collezioni/musei/museo-gregoriano-etrusco/sale-xvii-e-xviii--collezione-dei-vasi--ceramica-corinzia--lacon/kylix-laconica-con-prometeo-e-atlante.html"></IfcImage>
+<IfcImage image={<img src={require("@site/static/img/blog/2021-07-27/prometheus.jpeg").default} alt="PC image"></img>} ifcLink="https://www.museivaticani.va/content/museivaticani/en/collezioni/musei/museo-gregoriano-etrusco/sale-xvii-e-xviii--collezione-dei-vasi--ceramica-corinzia--lacon/kylix-laconica-con-prometeo-e-atlante.html"></IfcImage>
 
 Software is becoming more and more necessary in our work; if you are involved in BIM, you know this well.
 
-  🤯
+🤯
 In addition to BIM architect, I am also a programmer. I decided to try out a new programming tool: [WebStorm by JetBrains](https://www.jetbrains.com/webstorm/). My surprise was to discover its price: around **100 euros/license year**.
 
-  💰
+💰
 In contrast, some of the most popular BIM tools cost around **2500 euros/license year**. On top of that, they use proprietary formats, which means that the day you decide to stop using them, you lose access to all your work.
 
-  👨‍💼👨‍💼👨‍💼
+👨‍💼👨‍💼👨‍💼
 This is what happens when only a few have access to a resource that we all need; in this case, that resource is the **ability to create BIM software**. We can write all the [letters of complaint](https://gfxspeak.com/2020/08/04/architects-demand-autodesk/) we want, but the fact is that these software houses will keep doing what they do as long as we keep paying them.
 
-  <IfcCard>
-  💸
-Some BIM tools are around <b>25</b> times more expensive than software development tools.
-  </IfcCard>️
+<IfcCard>
+  💸 Some BIM tools are around <b>25</b> times more expensive than software development tools.
+</IfcCard>
+️
 
-  💪
+💪
 But that can change. Now, for the first time, we have the opportunity to bring BIM back to the industry. A BIM that is affordable, effective and that suits our needs: **a BIM made by us and for us**.
 
-  🤝
+🤝
 Maybe you think it's a bit utopian to think that we can stand up to the big commercial BIM houses with open source. However, don't forget that we are the source of money that keeps those big companies alive, and initiatives like [IFC.js](https://ifcjs.github.io/info/), [Speckle](https://speckle.systems/), [BlenderBIM](https://blenderbim.org/) and [OSArch](https://osarch.org/) keep growing every day.
 
-  🚀
-At the end of the day, you can keep wishing for a better industry while letting big companies take your money, or you can [contribute](https://discord.gg/FXfyR4XrKT) to create it. Sometimes, the only way to get what you need is to do it yourself.
+🚀
+At the end of the day, you can keep wishing for a better industry while letting big companies take your money, or you can [contribute](https://discord.gg/FXfyR4XrKT) to create it. Sometimes, the only way to get what you need is to do it yourself.