VSinerva/freesewing
1
0
Fork 0
Code Activity

chore: Port FreeSewing.dev to docusaurus

Browse source 
The replaces the NextJS site powering FreeSewing.dev with a Docusaurus
setup. It's part of my efforts to simplify FreeSewing's setup so we can
focus on our core value proposition.
This commit is contained in:
Joost De Cock 2024-09-28 13:13:48 +02:00
parent 497633d1d3
commit ab3204f9f1
692 changed files with 11037 additions and 20674 deletions
Download patch file Download diff file Expand all files Collapse all files

226
sites/dev/docs/tutorials/getting-started-codespaces/readme.mdx Normal file
View file

@ -0,0 +1,226 @@
---
title: Getting started with Codespaces
order: 13
---
:::note
This documentation assumes that you have a GitHub account with
a repository forked from `freesewing/freesewing`.
:::
## What is Codespaces?
[GitHub Codespaces][ghcs] (Codespaces) is an online service from
[GitHub][gh] that allows you to edit files and run computer programs
via a web browser.
The files and computer programs are hosted on and run from a remote
server run by GitHub.
[gh]: https://github.com
[ghcs]: https://github.com/features/codespaces
For FreeSewing, you can use Codespaces to edit our repository files to
modify existing designs, add new files to create new designs, and run
the FreeSewing lab website so you can test designs.
You can also edit, add, and test documentation files in Codespaces.
Because all of this is is done online via a web browser, you do not need
to have or use your own computer to perform this development work.
## Accessing Codespaces
Access Codespaces from the GitHub website while logged in:
- The "Your Codespaces" page is accessed via the "Codespaces" link at the top
of any GitHub page.
- A shortcut URL is: https://github.com/codespaces
## Creating a codespace
To create a new codespace:
- Select the "New codespace" button at the top of the Your Codespaces page.
- A shortcut URL is: https://github.com/codespaces/new
This will open a "Create a New Codespace" page.
On the Create a New Codespace page, select the options for your codespace:
- Repository -> ("`username/freesewing`" assuming that is the name of your GitHub repository)
- Branch -> (select the branch you want to use)
- Region -> (select the region most appropriate for you)
- Machine type -> (choose "2-core")
- Press the "Create codespace" button.
The Codespaces app will open in the browser window.
The Codespaces app is basically the [Visual Studio Code][vs] app with
Codespaces and GitHub integration built in.
[vs]: https://code.visualstudio.com
(Wait 45 seconds or so for the Codespace app to clone the repository from
GitHub to the codespace repository and start.)
## Editing files
You can browse and edit files in your codespace repository from within the app:
- On the Activity Bar on the far left side of the page, select the
Explorer icon.
(The icon looks like two pages of paper.)
- Use the Explorer sidebar to browse your repository and select a file to edit.
- Edit the file in the main window of the app.
## Saving, committing, and pushing changes
Auto-save is enabled by default, so any changes you make are
automatically saved in your codespace repository.
To commit changes to your codespace repository:
- In the Activity Bar on the far left side of the page,
select the Source Control icon.
- In the Source Control sidebar you can see a list of changed files.
- Press the "+" plus icon next to a file to stage it in preparation to
commit.
- Type a commit message in the text box and press the "Commit" button.
This commits the staged files to your codespace repository.
To push committed changes from your codespace repository back to your
GitHub repository:
- After committing changes to your codespace repository, press the
"Sync Changes" button to push the committed changes to your GitHub
repository.
- There is also an "..." ellipses menu at the top of the Source Control
sidebar that you can use.
Select the "Push" menu item.
## Running the lab, dev, and org websites
In the "Terminal" panel at the bottom of the page, you can run commands.
To start the lab website (to view and test new designs and design changes):
- In the Terminal panel, run `yarn kickstart` and then `yarn lab`.
To start the dev or org websites (to view and test documentation changes):
- dev: In the Terminal panel, run `cd sites/dev` and `yarn start`.
- org: In the Terminal panel, run `cd sites/org` and `yarn start`.
After the lab, dev, or org website starts:
- The usual `localhost:8000` port will automatically be forwarded to a custom
URL.
- A pop-up will appear saying that the port has been forwarded. The "Open in
browser" button on the pop-up will open a new browser tab/window with the
custom URL.
- You can also access the custom URL via the "Ports" panel.
:::tip
An example of a custom URL: `https://username-ominous-space-waffle-rwpgzw5q15vqc52q9-8000.preview.app.github.dev/`
:::
## To make a website publicly available
Forwarded ports are private by default.
The custom URL page is accessible only to you, the GitHub user
who owns the codespace, while you are logged into your GitHub account.
However, you can make the port public so others can access it
(or so you can access it on a different browser while not logged into GitHub).
To make the port public:
- In the Ports panel, right-click on the port and select
Port Visibility -> Public.
- The custom URL will be now be a publicly-accessible forwarded port.
You can copy and share the custom URL.
## Starting and stopping a codespace
You can start and stop your codespace via the Your Codespaces page.
- To start: Click on the codespace name to browse to the Codespaces
app URL for that codespace.
(You can also right-click to copy the URL and open it in a
different browser window.)
- To stop: Open the "..." ellipses menu next to the codespace
and select "Stop codespace".
:::warning
Codespaces continue to run unless explicitly stopped or the idle timeout is
reached.
(Closing the Codespaces app window does not stop the codespace.)
:::
## Renaming a codespace
Each new codespace is generated with a random name.
You can rename a codespace to make it easier to identify.
(This will help if you have more than one codespace.)
To rename a codespace:
- Go to the Your Codespaces page.
- Open the "..." ellipses menu next to the codespace
and select "Rename".
## Codespaces settings
You can access GitHub Settings via the user icon menu in the upper right
corner of any GitHub page (but not on the Codespaces app page).
- Selecting the "Settings" menu item will open the GitHub Settings page.
- The Codespaces settings are under "Codespaces" in the left sidebar
on the Settings page.
- A shortcut URL is: https://github.com/settings/codespaces
Among the Codespaces settings available are:
- "Default idle timeout" (how long codespaces continue to run when idle,
before being stopped)
- "Default retention period" (how long codespace repositories are kept
when unused, before being deleted)
:::note
Do not be confused by the other Settings icon/menu at the bottom left of the
Codespaces app page.
That is where settings for the Codespaces app and Visual Studio Code editor
are located.
:::
## Usage and Quotas
To check usage:
- Usage information is under "Billing and plans" in the left sidebar on
the Settings page.
- A shortcut URL is: https://github.com/settings/billing
About quotas:
- As a free account user, you have a quota of 120 core-hours of usage
and 15 GB of storage per billing month.
That is the total for all your codespaces combined.
- However, because your codespace uses a 2-core machine, you effectively
have only 60 hours of usage per month.
- (You can also select a 4-core machine for your codespace, but that
would reduce the effective usage quota to only 30 hours per month.)
- You will receive email notifications and and _toast_ messages in the
Codespaces app when you have used 75%, 90%, and 100% of your quotas.
- Quotas reset each month at the start of your account's billing cycle.
(Billing cycle start/end dates are different for each user.)
:::warning
Storage used by a codespace is counted against the quota regardless of
whether the codespace is running or stopped. If you are no longer
actively using a codespace, you may want to delete it so its storage
no longer continues to count towards your quota.
:::
:::tip
Don't worry -- you won't get a bill if you exceed your quota!
Instead, you will just be unable to start any of your codespaces
until the start of the next billing month.
And, if you have any work-in-progress changes that you need access to
before then, you can export those changes to a new GitHub branch.
:::
## Deleting a codespace
To delete a codespace:
- Go to the Your Codespaces page.
- Open the "..." ellipses menu next to the codespace
and select "Delete".
:::note RELATED
For more information, please see:
- [GitHub Codebases documentation](https://docs.github.com/en/codespaces).
- [About billing for GitHub Codespaces](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces)
:::