Skip to content

Commit f3c22a9

Browse files
paulrobertlloydpaulrobertlloyd
committed
docs: move local development to seperate page
1 parent c8cdb89 commit f3c22a9

File tree

3 files changed

+119
-117
lines changed

3 files changed

+119
-117
lines changed

‎docs/.vitepress/config.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ const sidebar = [
3535
{ text: "Accessibility statement", link: "/accessibility" },
3636
{ text: "Micropub clients", link: "/clients" },
3737
{ text: "Supported specifications", link: "/specifications" },
38+
{ text: "Local development", link: "/development" },
3839
],
3940
},
4041
];

‎docs/contributing.md‎

Lines changed: 2 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ We use GitHub issues to track bugs. Browse [existing reports](https://github.com
3232

3333
## Submit a fix
3434

35-
If you spot something broken and can supply a fix, [fork the project](https://github.com/getindiekit/indiekit/fork) and create a pull request. See [setting up a local development environment](#setting-up-a-local-development-environment) to get started.
35+
If you spot something broken and can supply a fix, [fork the project](https://github.com/getindiekit/indiekit/fork) and create a pull request. See [setting up a local development environment](development.md) to get started.
3636

3737
Commit messages for fixes should be prefixed with `fix:`, for example:
3838

@@ -62,119 +62,4 @@ You can use [Indiekit’s plug-in API](plugins/api/index.md) to add (or prototyp
6262

6363
When publishing a plug-in to the npm registry, add the `indiekit-plugin` keyword to help other Indiekit users find it. To have a plug-in listed [in the plug-in directory](https://getindiekit.com/plugins/), submit a pull request against the relevant page in the documentation.
6464

65-
## Setting up a local development environment
66-
67-
### Project structure
68-
69-
This project uses a monorepo structure, with concerns split into separate Node modules located in the `/packages` folder:
70-
71-
| Module{width=200px} | Purpose |
72-
| :----- | :------ |
73-
| `indiekit` | Coordinating functions and the Express web server. |
74-
| `frontend` | Frontend component library, used for the application interface. |
75-
| `error` | Error handling for the core module and plug-ins. |
76-
| `create-indiekit` | Project initialiser, used when running `npm create indiekit`. |
77-
| `endpoint-*` | Application endpoint plug-ins. |
78-
| `post-type-*` | Post type plug-ins. |
79-
| `preset-*` | Publication preset plug-ins. |
80-
| `store-*` | Content store plug-ins. |
81-
| `syndicator-*` | Syndicator plug-ins. |
82-
83-
Helper functions used in tests are in the `/helpers` folder.
84-
85-
### Project architecture
86-
87-
Indiekit uses the [Express server framework](https://expressjs.com).
88-
89-
Configuration defaults get merged with any user-defined values (Indiekit uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) to find and load a configuration object).
90-
91-
Plug-ins listed under the `plugins` array are then loaded and interrogated for known API methods, which further update the configuration.
92-
93-
Express waits for a resolved configuration file before starting the server.
94-
95-
### Running locally
96-
97-
To run the server locally, first install its dependencies:
98-
99-
```sh
100-
npm install
101-
```
102-
103-
The provided configuration file allows some options to be assigned using environment variables.
104-
105-
Create an `.env` file in the root of the project, for example:
106-
107-
```sh
108-
# Required
109-
PUBLICATION_URL="https://example.com"
110-
111-
# Database connection string URI (optional)
112-
MONGO_URL="mongodb://127.0.0.1:27017"
113-
114-
# Test saving files to a content store on GitHub (optional)
115-
GITHUB_USER="username"
116-
GITHUB_REPO="indiekit-test"
117-
GITHUB_BRANCH="main"
118-
GITHUB_TOKEN="12345abcde"
119-
120-
# Test syndicating content to a Mastodon server (optional)
121-
MASTODON_URL="https://example.social"
122-
MASTODON_USER="indiekit-test"
123-
MASTODON_ACCESS_TOKEN="12345abcde"
124-
```
125-
126-
You can then start the server:
127-
128-
```sh
129-
npm start
130-
```
131-
132-
To automatically restart the server whenever a file change is detected, use:
133-
134-
```sh
135-
npm run dev
136-
```
137-
138-
To enable authentication, use the `production` flag:
139-
140-
```sh
141-
npm run dev --production
142-
```
143-
144-
### Tests
145-
146-
The project uses both unit and integration tests. Run tests using the following command:
147-
148-
```sh
149-
npm test
150-
```
151-
152-
To run an individual test, use `node` followed by the path to the test. For example:
153-
154-
```sh
155-
node packages/indiekit/test/index.js
156-
```
157-
158-
### Test coverage
159-
160-
The project aims to achieve close to 100% test coverage. You can check code coverage by running the following command:
161-
162-
```sh
163-
npm run test:coverage
164-
```
165-
166-
### Linting
167-
168-
Consistent and high-quality code is maintained using [Prettier](https://prettier.io) with [ESLint](https://eslint.org) used to check JavaScript files and [Stylelint](https://stylelint.io) used to check CSS stylesheets.
169-
170-
You can check that any changes use the preferred code style by running the following command:
171-
172-
```sh
173-
npm run lint
174-
```
175-
176-
You automatically fix any issues by running the following command:
177-
178-
```sh
179-
npm run lint:fix
180-
```
65+
See also [Setting up a local development environment](development.md).

‎docs/development.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Setting up a local development environment
2+
3+
## Project structure
4+
5+
This project uses a monorepo structure, with concerns split into separate Node modules located in the `/packages` folder:
6+
7+
| Module{width=200px} | Purpose |
8+
| :----- | :------ |
9+
| `indiekit` | Coordinating functions and the Express web server. |
10+
| `frontend` | Frontend component library, used for the application interface. |
11+
| `error` | Error handling for the core module and plug-ins. |
12+
| `create-indiekit` | Project initialiser, used when running `npm create indiekit`. |
13+
| `endpoint-*` | Application endpoint plug-ins. |
14+
| `post-type-*` | Post type plug-ins. |
15+
| `preset-*` | Publication preset plug-ins. |
16+
| `store-*` | Content store plug-ins. |
17+
| `syndicator-*` | Syndicator plug-ins. |
18+
19+
Helper functions used in tests are in the `/helpers` folder.
20+
21+
## Project architecture
22+
23+
Indiekit uses the [Express server framework](https://expressjs.com).
24+
25+
Configuration defaults get merged with any user-defined values (Indiekit uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) to find and load a configuration object).
26+
27+
Plug-ins listed under the `plugins` array are then loaded and interrogated for known API methods, which further update the configuration.
28+
29+
Express waits for a resolved configuration file before starting the server.
30+
31+
## Running locally
32+
33+
To run the server locally, first install its dependencies:
34+
35+
```sh
36+
npm install
37+
```
38+
39+
The provided configuration file allows some options to be assigned using environment variables.
40+
41+
Create an `.env` file in the root of the project, for example:
42+
43+
```sh
44+
# Required
45+
PUBLICATION_URL="https://example.com"
46+
47+
# Database connection string URI (optional)
48+
MONGO_URL="mongodb://127.0.0.1:27017"
49+
50+
# Test saving files to a content store on GitHub (optional)
51+
GITHUB_USER="username"
52+
GITHUB_REPO="indiekit-test"
53+
GITHUB_BRANCH="main"
54+
GITHUB_TOKEN="12345abcde"
55+
56+
# Test syndicating content to a Mastodon server (optional)
57+
MASTODON_URL="https://example.social"
58+
MASTODON_USER="indiekit-test"
59+
MASTODON_ACCESS_TOKEN="12345abcde"
60+
```
61+
62+
You can then start the server:
63+
64+
```sh
65+
npm start
66+
```
67+
68+
To automatically restart the server whenever a file change is detected, use:
69+
70+
```sh
71+
npm run dev
72+
```
73+
74+
To enable authentication, use the `production` flag:
75+
76+
```sh
77+
npm run dev --production
78+
```
79+
80+
## Tests
81+
82+
The project uses both unit and integration tests. Run tests using the following command:
83+
84+
```sh
85+
npm test
86+
```
87+
88+
To run an individual test, use `node` followed by the path to the test. For example:
89+
90+
```sh
91+
node packages/indiekit/test/index.js
92+
```
93+
94+
## Test coverage
95+
96+
The project aims to achieve close to 100% test coverage. You can check code coverage by running the following command:
97+
98+
```sh
99+
npm run test:coverage
100+
```
101+
102+
## Linting
103+
104+
Consistent and high-quality code is maintained using [Prettier](https://prettier.io) with [ESLint](https://eslint.org) used to check JavaScript files and [Stylelint](https://stylelint.io) used to check CSS stylesheets.
105+
106+
You can check that any changes use the preferred code style by running the following command:
107+
108+
```sh
109+
npm run lint
110+
```
111+
112+
You automatically fix any issues by running the following command:
113+
114+
```sh
115+
npm run lint:fix
116+
```

0 commit comments

Comments
 (0)