# Getting Started

> Note: The package manager this project uses is Yarn. If you do not have it, follow the [installation instructions](https://yarnpkg.com/en/docs/install).

First, clone this repository.

`git clone https://github.com/Jake-Short/nextjs-docs-generator.git`\
\
Then, CD into the directory, install NPM modules, and run the development server.

```
cd nextjs-docs-generator

yarn

yarn dev
```

Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

## Developing

To edit the markdown, you can use the button above to switch to markdown mode. You can also 
open the generated .md file in your favorite code editor.\
\
The .md file is located inside the "markdown" folder in the root of the project. It will have a name similar to the one you 
entered (spaces are replaced with "-", and non-alphanumeric characters are removed).

>? Note: The markdown editor is only available on desktop. On mobile, the site will show without editing options.

> Note: When using the markdown editor, your changes will automatically be saved a few seconds after you stop typing.

## Building for production

To generate the Next.js site, run `yarn gen`. This will generate the Next.js site inside of the `site` folder. After generating, to build the final Next.js site for production, run:
```
cd site

yarn

yarn build

# optionally to run the built site locally
yarn start
```
For more information about Next.js sites, you can visit the [Next.js docs](https://nextjs.org/docs/getting-started).

## Important notes

### Deleting a page

To delete a page, simply delete the .md file.

### Changing URL route (renaming a .md file)

Renaming a .md file will change the route that is shown in the URL for the particular .md file.

### Renaming a page

To rename a page (the name shown in the sidebar), edit the metadata attribute `sidebarText` at the top of the .md file.

### Rearranging pages

To rearrange pages under a sidebar header, change the `order` attribute in the .md file. Pages under the same sidebar header will be arranged least-to-greatest based on the `order` attribute.

### Renaming a sidebar header

To rename a sidebar header, simply change the name of the folder that holds the relevant .md files.

### Rearranging sidebar headers

To rearrange sidebar headers, create a file named `_order`, with the contents being solely a number, inside of the relevant folders in the `markdown` folder. Sidebar headers will be arranged least-to-greatest based on the contents of the `_order` files.

### Adding NPM packages

NPM packages can be added and used, and they will carry over into the final build without any additional actions.

# Deployment

There are multiple ways to deploy this site. Next.js is built by [Vercel](https://vercel.com), so the hosting integration with them is nice. Read below to learn about the options for deployment.

## [Vercel](https://vercel.com)

To deploy to Vercel, upload the project to GitHub, GitLab, or Bitbucket. Then, on [Vercel](https://vercel.com), import the repository.\
\
You will see a screen titled `Import Project`. On that page, click the `Build and Output Settings`. You will need to input the following values (you will have to click the override slider):
- Build Command: `yarn gen && cd site && yarn build`

- Output Directory: `site/.next`

The page should look like this:\
\
<img src="https://imgur.com/BT4HLQI.png" width="100%" style="box-shadow: 0px 0px 6px 2px rgba(0, 0, 0, 0.07); max-width: 550px;" />\
\
You're done! Vercel should automatically build and deploy your site.

### Alternative Vercel Deployment

Alternatively, you can run `yarn gen`, which generates a Next.js site in the `site` folder. Upload the contents of that folder to a GitHub, GitLab, or Bitbucket repository.\
\
Next, go to [Vercel](https://vercel.com), and connect your GitHub repository. Vercel should detect that it is a Next.js site and automatically select the correct framework preset.\
\
You're done! Vercel should build and deploy your site.

## [Netlify](https://netlify.com)

To deploy on Netlify, upload the project to GitHub, GitLab, or Bitbucket. Then, on [Netlify](https://netlify.com), import the repository.\
\
You will see a screen titled `Create a new site`, on step 3: `Build options, and deploy!`. On that page, you will need to input the following values:
- Build Command: `yarn gen && cd site && yarn build && yarn export`

- Publish Directory: `site/out`

The page should look like this:\
\
<img src="https://imgur.com/KwUyfnn.png" width="100%" style="box-shadow: 0px 0px 6px 2px rgba(0, 0, 0, 0.07); max-width: 550px;" />\
\
You're done! Netlify should automatically build and deploy your site.

# Update

## Checking version

To check the version you are on, you can run the command `yarn ver`. This will output something such as `1.0.0`. To view the latest version of the project, view the [releases](https://github.com/Jake-Short/nextjs-docs-generator/releases) on the [GitHub repository](https://github.com/Jake-Short/nextjs-docs-generator).

## Updating

You are able to update your project to include new changes in the GitHub repository. To get started, run `yarn update`. This will first download the latest GitHub repository version to a temporary directory.\
\
After running that command, you will be asked to select which of the following folders you want to update:
`internal, styles, pages, components`.\
\
After choosing the folders to update, and confirming your actions, the new folders (as selected above) will overwrite the old ones.

>! Be careful which folders you choose to update! All files will be overwritten with the new ones.

# Open source

This project is completely open source! Feel free to contribute or create issues in the [GitHub repository](https://github.com/Jake-Short/nextjs-docs-generator).

## Contributing

Contributions are always welcome! To get started, refer to the [CONTRIBUTING.md](https://github.com/Jake-Short/nextjs-docs-generator/blob/main/CONTRIBUTING.md) file on the [GitHub repository](https://github.com/Jake-Short/nextjs-docs-generator).

## Creator

This project was started by and is maintained by [Jake Short](https://github.com/jake-short).

# Code highlighting

You can change the code highlighting theme by changing the imported theme inside the `components/codeblock.js` file.\
\
Change the `xcode` portion of this line to one of the other available themes:
```
import codeTheme from 'react-syntax-highlighter/dist/cjs/styles/hljs/xcode';
```
You can view a preview of possible themes [here](https://highlightjs.org/static/demo/).

# Customizing the navigation bar

You can customize the JSX and CSS used to build the navigation bar.

## Changing/adding a logo

You can add a logo to the sidebar in a few steps. First, open the `components/sidebar.js` file. Near the top of the file, you will see this section:

```javascript
// Update path to logo here
const logo = require('../public/logo.svg');

// Set to false to have no logo
const logoIsShown = false;

// Centered logo
const centeredLogo = false;
```

First, set `logoIsShown` to true, then change `../public/logo.svg` to the path of your logo. Alternatively, replace the logo.svg file with your own logo.

## Changing the JSX

To alter the JSX, you can edit the `components/sidebar.js` file.

>! This file contains functions to add a page and add a new section. It is not recommended to change these functions.

## Changing the CSS

To alter the CSS, you can edit the `styles/sidebar.module.css` file.

# Customizing the landing/index page

This is the page that is shown at the base route (i.e. localhost:3000).

## Changing the JSX

To alter the JSX, you can edit the `components/indexcontent.js` file.

## Changing the CSS

To alter the CSS, you can edit the `styles/index.module.css` file.

## Changes to index.js

The index.js page handles the  rendering, routing, and other functions involved with the operation of the site. Altering it is not recommended, but if necessary, can be done. See the following sections to learn about the necessary changes.

- Altering the development index.js file can be accomplished by changing the `pages/index.js` file. *These changes will only work in development, see below for production.*

- Altering the production index.js file can be accomplished by changing the `internal/buildfiles/index.js` and `internal/buildfiles/[index].js` file.

>! Note: There are slight differences between the two index files in the buildfiles folder. For example, index.js does not have getStaticPaths. These differences are important!

# Styling

There are a few options to choose from when styling the site. Read below about the possibilities.

## Themes

When running the site via `yarn dev`, the `styling-theming` page will have a themes section, where you can choose from one of the pre-built themes.

> A theme works by changing the variables in the `styles/variables.css` file to those of a pre-built theme.

## CSS Variables

Many aspects of the site, such as accent color, root font size, background color, and more can be altered inside of the `styles/variables.css` file. This file contains CSS variables, along with a description for all of the variables.

## Altering the CSS

In addition to altering the CSS variables, you can also edit the CSS directly. You can change any of the files inside of the `styles` folder to suit your needs.

# Altering the runtime server

If necessary, the runtime server *can* be altered.

>! Altering this is not recommended. The runtime server interacts with the file system (creating and saving .md files) and serves the content when running in development. Altering the functionality of this could cause issues.

## Development runtime server

To make changes to the runtime server that is used during development (`yarn dev`) you can change the `internal/runtimeserver.js` file.