Skip to content

docusaurus docs implementation #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
iduuck wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

docusaurus docs implementation #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9f51a32
docs: implement first version of the documentations
Sep 28, 2020
8e824cc
chore: remove readme’s & add gitkeeps
Sep 28, 2020
691ee04
docs: fix internal reference issues
Sep 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Empty file added components/.gitkeep
View file
Open in desktop
Empty file.
11 changes: 0 additions & 11 deletions components/README.md
View file
Open in desktop

This file was deleted.

20 changes: 20 additions & 0 deletions docs/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Dependencies
/node_modules

# Production
/build

# Generated files
.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*
33 changes: 33 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Website

This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.

### Installation

```
$ yarn
```

### Local Development

```
$ yarn start
```

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

### Build

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.

### Deployment

```
$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
3 changes: 3 additions & 0 deletions docs/babel.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
7 changes: 7 additions & 0 deletions docs/docs/caveats-autocorrect-eslint.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
id: eslint
title: Auto-fix with ESLint
slug: /caveats/eslint
---

While developing the boilerplate it came to our mind, that ESLint is mostly transitioning to the usage of an **explicit** setting for "auto-correcting on save".
16 changes: 16 additions & 0 deletions docs/docs/caveats-using-gittower.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
id: gittower
title: Using Tower
slug: /caveats/gittower
---

We found out, that there is an issue with using Tower and the preconfigured git hooks.
This page is just a reminder that you need to configure Tower to be compliant with the boilerplate.

### Create a new environment file

Using [this guide](https://www.git-tower.com/help/guides/integration/environment/mac), will help you configuring Tower to use the git-hooks to verify some sort of default behavior for your team.

### Using ASDF as version manager?

When you are using asdf, we are sad to tell you, that the git-hooks aren't working at all in Tower for you.
40 changes: 40 additions & 0 deletions docs/docs/deployment-heroku.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
id: deployment-on-heroku
title: Deployment on Heroku
sidebar_label: Heroku
slug: /deployment/heroku
---

Next.js is a very nice tool, when it comes to easy deployment, since you do not need to setup everything from scratch. You could simply run `yarn build` & `yarn start` (more about scripts in the "scripts" document), and the application is running on the machine. However, Heroku on the other side, has no "real" build step, so we need to utilize the NPM scripts a little and add some more scripts for building the application on Heroku. Because what we don't want is to build the application on our own machine and then commit everything to version control.

### Step 1: Customize the package.json

We need to add a custom [NPM script](./features-scripts.md) to our `package.json` to enable the build step for Heroku. For this, add the following line of code into the "scripts" section of your `package.json`:

```json
{
// [...]
"scripts": {
// [...]
"heroku-postbuild": "yarn build"
// [...]
}
// [...]
}
```

### Step 2: Add a `Procfile` to the root of your project

By now, you should be able to be up and running on your next deployment/push to the Heroku servers, since the `start` NPM script is the default process for the `web` instance for them. However, to be 100% sure for later usage or when adding some sort of custom environment variables to the server, you need to add this simple line in a new file called `Procfile`.

```shell script
web: yarn start
```

:::tip What is a `Procfile`?
`Procfile` is an abbreviation for the word "process file". Here we are specifying our processes Heroku should run.
:::

### Step 3: Push to Heroku

Add all files to git, commit and push to the Git servers you are using. PROFIT!
8 changes: 8 additions & 0 deletions docs/docs/deployment-vercel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
id: deployment-on-vercel
title: Deployment on Vercel
sidebar_label: Vercel
slug: /deployment/vercel
---

Vercel and Next.js came from the same developer team, hence why you don't need to configure anything in the code. Also Vercel's project settings are almost ready to go without tweaking with Next.js.
34 changes: 34 additions & 0 deletions docs/docs/features-git-hooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
id: git-hooks
title: Husky Configuration
---

## Hooks

### `commit-msg`

#### What is going to be checked?

On `commit-msg` we are checking for the conformity of the commit-message to the conventional-changelog message styleguide using the `commitlint` CLI.

#### Scripts running

When a commit message is composed, `commitlint` is being run.

### `pre-commit`

#### What is going to be checked?

When commiting we are linting the code for typescript issues, and for eslint issues that are being reported. A negative signal of the CLI is prompting the user to fix the problems and commit again.

#### Scripts running

When a commit is prepared, `yarn lint` is being run. You can find the definition of the npm scripts in the [scripts](./features-scripts.md) section of this documentation.

### `pre-push`

Soon to come. We are going to implement a test-driven system here, since tests are to complex to check in a `pre-commit` system.

## Caveats

You are not able to use Tower to commit or even use the git-hooks since Tower doesn't come with a proper shell environment. [Read more.](./caveats-using-gittower.md)
19 changes: 19 additions & 0 deletions docs/docs/features-scripts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
id: scripts
title: NPM Scripts
slug: /npm-scripts
---

This document features an overview of scripts we are including by default in our boilerplate.

### Core Scripts

| Name | Purpose |
| --- | --- |
| `dev` | Start the Next.js development server. Important to use this one in development. `start` is only for running the server in production mode.|
| `build` | Build the next.js project. Prepare the project to be run on the server through the `start` script. |
| `start` | Start the production server. |

### Additional Scripts

TBD
29 changes: 29 additions & 0 deletions docs/docs/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
id: features
title: Features
sidebar_label: Overview
slug: /features
---

Following is an overview of things we have included in our boilerplate. Rather than including a "Getting started" guide with each of the frameworks/features we include, please refer to the documentations of the libraries itself.

### Included libraries

- [Next.js](https://nextjs.org/)
- [mobx-state-tree](https://mobx-state-tree.js.org/intro/philosophy)
- [styled-components](https://styled-components.com/) ([NPM](https://www.npmjs.com/package/styled-components))
- [styled-reset](https://www.npmjs.com/package/styled-reset)

### Development libraries

- [husky](https://github.com/typicode/husky)
- [TypeScript](https://www.typescriptlang.org/) ([NPM](https://www.npmjs.com/package/typescript))
- [eslint](https://eslint.org/) ([NPM](https://www.npmjs.com/package/eslint))
- [prettier](https://prettier.io/) ([NPM](https://www.npmjs.com/package/prettier))
- [@fintory/eslint-config](https://github.com/fintory/eslint-config) ([NPM](https://www.npmjs.com/package/@fintory/eslint-config))

---

### Documentations of other third-party libraries

TBD – Please insert documentations of third-party libraries as they are added.
7 changes: 7 additions & 0 deletions docs/docs/i18n.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
id: i18n
title: Internationalization
---

We decided not to ship i18n support, since we don't need this by default on every and each project.
This is a small guide on getting you up and running with `react-intl` on the boilerplate.
20 changes: 20 additions & 0 deletions docs/docs/project-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
id: project-structure
title: Project Structure
sidebar_label: Project Structure
slug: /
---

The project structure is a little different than the one you are having with a normal React.js project (i.e. with `create-react-app`). However we are pretty similar with the `create-next-app` setup, except some minor changes in the folder structure. See below, for what each folder is here, and why it is necessary.

The checkmark (✅), or cross (❌) is used for identifying, whether it is safe to remove the folder after cloning, or not.

| Folder | What's included? | |
| --- | --- | --- |
| `components` | Global components, should be familiar when working with React.js | ❌ |
| `docs` | You can remove this folder safely. Those are just the docs you are currently reading. | ✅ |
| `pages` | The `pages` folder represents both, the screens and the routing of the Next.js application your are going to write. | ❌ |
| `public` | The public folder is for holding assets, sitemaps, etc. | ❌ |
| `sections` | Sections are here for you to be a little more structure while developing landing pages. You can remove this one safely. | ✅ |
| `store` | Since we are using `mobx-state-tree` in the boilerplate, we encourage you to store your stores here. | ❌ |
| `utils` | This is a little folder just for the sake of being available. If you have some utility functions, please place them here. | ❌ |
26 changes: 26 additions & 0 deletions docs/docs/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
id: setup
title: Setup
slug: /setup
---

You can use this boilerplate very easily. Just follow the following steps:

## Using the GitHub template

### Step 1: "Use this template"

![](/img/github-template-screenshot.png)

### Step 2: Enter all preferences of your new project

In the screen the page is referring you to, you are seeing a form, where you need to name the repository and specify whether the project is public or private.

:::danger
Please be careful with public repositories.
:::


### Step 3: Remove unused folders

If you want to keep the project clean, and don't want to document everything you do in the new project, you are free to remove some folders. You can have a look at the "[Project Structure](./project-structure.md)" document, whether the folder is safe to remove or not.
99 changes: 99 additions & 0 deletions docs/docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
module.exports = {
title: 'boot-next',
tagline: 'Opinionated boilerplate by @fintory',
url: 'https://your-docusaurus-test-site.com',
baseUrl: '/',
onBrokenLinks: 'throw',
favicon: 'img/favicon.ico',
organizationName: 'fintory', // Usually your GitHub org/user name.
projectName: 'boot-next', // Usually your repo name.
themeConfig: {
navbar: {
title: 'boot-next',
logo: {
alt: 'boot-next Logo',
src: 'img/logo.svg',
},
items: [
{
to: 'docs/',
activeBasePath: 'docs',
label: 'Docs',
position: 'left',
},
{
to: 'https://fintory.com/',
activeBasePath: '. ',
label: 'Fintory',
position: 'left',
},
{
href: 'https://github.com/fintory/boot-next',
label: 'GitHub',
position: 'right',
},
],
},
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Style Guide',
to: 'docs/',
},
{
label: 'Second Doc',
to: 'docs/doc2/',
},
],
},
{
title: 'Community',
items: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'Twitter',
href: 'https://twitter.com/docusaurus',
},
],
},
{
title: 'More',
items: [
{
label: 'GitHub',
href: 'https://github.com/facebook/docusaurus',
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} Fintory. Built with Docusaurus.`,
},
},
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
// Please change this to your repo.
editUrl:
'https://github.com/facebook/docusaurus/edit/master/website/',
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
},
],
],
}
Loading