Skip to content

Update readme #153

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.

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

Merged
merged 1 commit into from
Sep 27, 2024
Merged
Changes from all commits
Commits
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
44 changes: 25 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,42 +1,48 @@
# MonoGame.github.io

This repository contains the documentation and the website for MonoGame.
This repository contains the source code for the [MonoGame](https://monogame.net) website. If you're looking for the documentation, visit the [Documentation](https://github.com/monogame/docs.monogame.github.io) repository.

## Building Form Source
## Prerequisites

The MonoGame website is built using the .NET tool [DocFX](https://dotnet.github.io/docfx/) to generate the API reference documentation and the static site generator [11ty](https://www.11ty.dev/) to generate the full website. This means you will need the following prerequisites to build locally from source
To build and run the MonoGame website locally, you will need
- [Node.js and NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)

1. .NET SDK version 6.0 or higher installed ([download](https://dotnet.microsoft.com/en-us/download))
2. Node.js and NPM installed ([download](https://nodejs.org/en))
## Running the Website Locally
The MonoGame website is built using [11ty (Eleventy)](https://www.11ty.dev/), a static site generator. To start working with the site on your local machine, follow these steps:

With your environment setup properly, the following explains how to build from source

1. Clone this repository
1. **Clone this repository**

```sh
git clone https://github.com/MonoGame/monogame.github.io.git
```

2. Install npm dependencies
2. **Install npm dependencies**

In the root directory of the cloned repository, run:

```sh
npm install
```

3. Optional Steps
3. **Start the development server**

To serve the site locally with hot-reloading, which allows you to see changes in real-time, use the following command

```sh
npm run dev
```

This will spin up a local server, the address of which will be shown in the console.

If you want to generate the API Reference documentation locally, you will need to ensure that the MonoGame submodule has been initialized by running
## Building the Site for Production

`git submodule update --init --recursive`
To generate a production-ready build of the site, run:

4. Run a local build and serve it with hot reloading. Depending on what part of the site you are working on, there are different commands you can use. They are explained in the table below
```sh
npm run build
```

| Command | Generates Website | Generates Articles | Generates API | Description |
| --- | --- | --- | --- | --- |
| `npm run dev` | ✔ | ✔ | ✔ | This will run and serve the full website, including the web pages generated by 11ty and the articles and api documentation built by docfx. This can be slower to use when developing since all API documentation (~500 files) will be built initially and again during each hot reload change. If you're not working specifically on the API documentation page, it is suggested to use one of the other commands instead. |
| `npm run website` | ✔ | ❌ | ❌ | This will run and serve the website with only the web pages generated by 11ty. The articles and api documentation generated by docfx will be bypassed. This is useful when you're only working on the main website pages and want fast hot reloading.|
| `npm run articles` | ✔ | ✔ | ❌ | This will run and serve the website including the webpages generated by 11ty and the articles generated by docfx only. It will not generate the API documentation. This is to allow fast hot reloading while working on the articles by not having all API documentation files (~500 files) be included. |
| `npm run build` | ✔ | ✔ | ✔ | This will perform a full build of the website, including the web pages built in 11ty and the articles and api documentation built by docfx. |
This will generate the static HTML file in the `_site` directory.

## LICENSE

Expand Down