Skip to content
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

Building uppy.io/docs VS uppy.io/blog #243

Merged
merged 3 commits into from
Jul 3, 2024
Merged

Building uppy.io/docs VS uppy.io/blog #243

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6c30c24
README.md - add explanation of uppy.io/docs VS uppy.io/blog
lakesare May 15, 2024
f70cb4a
Apply suggestions from code review
lakesare May 21, 2024
a00fa09
Merge branch 'main' into lakesare/readme-about-docs
lakesare Jul 2, 2024
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
45 changes: 39 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,32 @@
# Uppy.io

Website and documentation for [uppy](https://uppy.io/).
Website and documentation for [uppy.io](https://uppy.io).
lakesare marked this conversation as resolved.
Show resolved Hide resolved

This website is built using [Docusaurus 2](https://docusaurus.io/), a modern
static website generator.
Code for [uppy.io/blog](https://uppy.io/blog) lives in this repo.
Code for [uppy.io/docs](https://uppy.io/docs/quick-start) lives in
[github.com/transloadit/uppy](https://github.com/transloadit/uppy).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[github.com/transloadit/uppy](https://github.com/transloadit/uppy).
[transloadit/uppy](https://github.com/transloadit/uppy).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why? I feel github.com prefix makes it more intelligible, and removes the need to remember github-specific shortcuts.


## Developer guide

### Installation
If you want to edit [uppy.io/blog](https://uppy.io/blog), just edit the files in
this repo.

If you want to edit [uppy.io/docs](https://uppy.io/docs/quick-start), then you
should:

1. Clone both the **uppy** repo and **uppy.io** repo.
lakesare marked this conversation as resolved.
Show resolved Hide resolved

2. Then, from your `uppy.io` clone, run:

```sh
ln -s /path-to-your-uppy-repo/docs docs
```

Now, treat **/uppy/docs** as your working directory, but run the build/lint
scripts from your **/uppy.io** directory - **/uppy.io** will pick up your
changes.
Comment on lines +25 to +27
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really understand the "treat as your working directory"

Suggested change
Now, treat **/uppy/docs** as your working directory, but run the build/lint
scripts from your **/uppy.io** directory - **/uppy.io** will pick up your
changes.
Now, when running the build/lint scripts from the root of your `transloadit/uppy.io` clone, it will pick up your local changes on the `docs/` folder. Note that changes in the `docs/` changes should be submitted to the `transloadit/uppy` repository.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"treat /uppy/docs as your working directory" means "/uppy/docs is a folder where you will be editing files, then committing the files, and then pushing the files".


### Install Dependencies

```sh
corepack yarn
Expand All @@ -19,8 +38,17 @@ corepack yarn
corepack yarn dev
```

This command starts a local development server and opens up a browser window.
Most changes are reflected live without having to restart the server.
This command builds **/uppy/docs** and **/uppy.io**, and shows them in a
browser. Most changes are reflected live without having to restart the server.
Comment on lines +41 to +42
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the previous sentence was clearer. Can you explain what you don't like about it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to make it explicit that both /uppy/docs and /uppy.io will be built using this command.


### Lint

```sh
corepack yarn run format
corepack yarn lint
```

This command lints **/uppy/docs** and **/uppy.io**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This command lints **/uppy/docs** and **/uppy.io**.
N.B.: These commands will also report lint errors from the `docs` folder that's hosted on the `transloadit/uppy` repository.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My version is more consistent with the phrasing of other command descriptions.


### Build

Expand All @@ -30,3 +58,8 @@ corepack yarn build

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

---

This website is built using [Docusaurus 2](https://docusaurus.io/), a modern
static website generator.
lakesare marked this conversation as resolved.
Show resolved Hide resolved