Updated Documentations to V1.0
This commit is contained in:
parent
668ef6a93e
commit
9f4b49ca4f
76
website/docs-marcsync-dev/docs/classes/Collection.mdx
Normal file
76
website/docs-marcsync-dev/docs/classes/Collection.mdx
Normal file
@ -0,0 +1,76 @@
|
||||
# Collection
|
||||
|
||||
Collection is a class that represents a collection in the MarcSync API.
|
||||
|
||||
<div style={{display: "grid", "grid-template-columns": "repeat(2,minmax(0,1fr))", "box-sizing": "border-box", "border-width": "0", "border-style": "solid", "word-break": "break-word"}}>
|
||||
|
||||
<div style={{"box-sizing": "border-box", "border-width": "0", "border-style": "solid", "word-break": "break-word", "font-weight": "600"}}>
|
||||
METHODS
|
||||
<ul style={{"padding-left": ".5rem", "list-style-type": "disc", "margin-bottom": "1.25rem", "list-style": "none", "box-sizing": "border-box", "border-width": "0", "border-style": "solid", "word-break": "break-word", "font-weight": "500"}}>
|
||||
<li style={{"margin-bottom": ".5rem", "list-style-type": "none"}}>
|
||||
<a style={{"display": "block"}} href="#createEntry">createEntry</a>
|
||||
<a style={{"display": "block"}} href="#updateEntries">updateEntries</a>
|
||||
<a style={{"display": "block"}} href="#getEntries">getEntries</a>
|
||||
<a style={{"display": "block"}} href="#deleteEntries">deleteEntries</a>
|
||||
<a style={{"display": "block"}} href="#drop">drop</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
## METHODS
|
||||
|
||||
### :createEntry(`data:` [EntryData](../types/EntryData))
|
||||
Creates a new entry in the collection and returns it as an [Entry](./Entry) object.
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
[InvalidAccessToken](../errors/Authorization#InvalidAccessToken) - Thrown when the `accessToken` is invalid.<br/>
|
||||
[CollectionNotFound](../errors/Collection#CollectionNotFound) - Thrown when the collection does not exist.<br/>
|
||||
[InvalidEntryData](../errors/Entry#InvalidEntryData) - Thrown when the [EntryData](../types/EntryData) is invalid.
|
||||
|
||||
:::
|
||||
|
||||
### :updateEntries(`filters:` [EntryData](../types/EntryData), `data:` [EntryData](../types/EntryData))
|
||||
Updates all entries that match the specified filters with the specified data.
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
[InvalidAccessToken](../errors/Authorization#InvalidAccessToken) - Thrown when the `accessToken` is invalid.<br/>
|
||||
[CollectionNotFound](../errors/Collection#CollectionNotFound) - Thrown when the collection does not exist.<br/>
|
||||
[InvalidEntryData](../errors/Entry#InvalidEntryData) - Thrown when the [EntryData](../types/EntryData) is invalid.
|
||||
|
||||
:::
|
||||
|
||||
### :getEntries(`filters:` [EntryData](../types/EntryData))
|
||||
Returns all entries that match the specified filters as an array of [Entry](./Entry) objects.
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
[InvalidAccessToken](../errors/Authorization#InvalidAccessToken) - Thrown when the `accessToken` is invalid.<br/>
|
||||
[CollectionNotFound](../errors/Collection#CollectionNotFound) - Thrown when the collection does not exist.<br/>
|
||||
[InvalidEntryData](../errors/Entry#InvalidEntryData) - Thrown when the [EntryData](../types/EntryData) is invalid.
|
||||
|
||||
:::
|
||||
|
||||
### :deleteEntries(`filters:` [EntryData](../types/EntryData))
|
||||
Deletes all entries that match the specified filters.
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
[InvalidAccessToken](../errors/Authorization#InvalidAccessToken) - Thrown when the `accessToken` is invalid.<br/>
|
||||
[CollectionNotFound](../errors/Collection#CollectionNotFound) - Thrown when the collection does not exist.<br/>
|
||||
[InvalidEntryData](../errors/Entry#InvalidEntryData) - Thrown when the [EntryData](../types/EntryData) is invalid.
|
||||
|
||||
:::
|
||||
|
||||
### :drop()
|
||||
Deletes the collection.
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
[InvalidAccessToken](../errors/Authorization#InvalidAccessToken) - Thrown when the `accessToken` is invalid.<br/>
|
||||
[CollectionNotFound](../errors/Collection#CollectionNotFound) - Thrown when the collection does not exist.<br/>
|
||||
|
||||
:::
|
||||
49
website/docs-marcsync-dev/docs/classes/Entry.mdx
Normal file
49
website/docs-marcsync-dev/docs/classes/Entry.mdx
Normal file
@ -0,0 +1,49 @@
|
||||
# Entry
|
||||
|
||||
Entry is a class that represents an entry in the MarcSync API.
|
||||
|
||||
<div style={{display: "grid", "grid-template-columns": "repeat(2,minmax(0,1fr))", "box-sizing": "border-box", "border-width": "0", "border-style": "solid", "word-break": "break-word"}}>
|
||||
|
||||
<div style={{"box-sizing": "border-box", "border-width": "0", "border-style": "solid", "word-break": "break-word", "font-weight": "600"}}>
|
||||
METHODS
|
||||
<ul style={{"padding-left": ".5rem", "list-style-type": "disc", "margin-bottom": "1.25rem", "list-style": "none", "box-sizing": "border-box", "border-width": "0", "border-style": "solid", "word-break": "break-word", "font-weight": "500"}}>
|
||||
<li style={{"margin-bottom": ".5rem", "list-style-type": "none"}}>
|
||||
<a style={{"display": "block"}} href="#getValues">getValues</a>
|
||||
<a style={{"display": "block"}} href="#getValue">getValue</a>
|
||||
<a style={{"display": "block"}} href="#updateValues">updateValues</a>
|
||||
<a style={{"display": "block"}} href="#delete">delete</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
## METHODS
|
||||
|
||||
### :getValues()
|
||||
Returns all values of the entry as [EntryData](../types/EntryData).
|
||||
|
||||
|
||||
### :getValue(`key:` [string](https://www.lua.org/pil/2.4.html))
|
||||
Returns the value of the specified key.
|
||||
|
||||
### :updateValues(`data:` [EntryData](../types/EntryData))
|
||||
Updates the values of the entry with the specified data.
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
[InvalidAccessToken](../errors/Authorization#InvalidAccessToken) - Thrown when the `accessToken` is invalid.<br/>
|
||||
[CollectionNotFound](../errors/Collection#CollectionNotFound) - Thrown when the collection does not exist.<br/>
|
||||
[InvalidEntryData](../errors/Entry#InvalidEntryData) - Thrown when the [EntryData](../types/EntryData) is invalid.
|
||||
|
||||
:::
|
||||
|
||||
### :delete()
|
||||
Deletes the entry.
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
[InvalidAccessToken](../errors/Authorization#InvalidAccessToken) - Thrown when the `accessToken` is invalid.<br/>
|
||||
[CollectionNotFound](../errors/Collection#CollectionNotFound) - Thrown when the collection does not exist.<br/>
|
||||
|
||||
:::
|
||||
52
website/docs-marcsync-dev/docs/classes/MarcSyncClient.mdx
Normal file
52
website/docs-marcsync-dev/docs/classes/MarcSyncClient.mdx
Normal file
@ -0,0 +1,52 @@
|
||||
# MarcSyncClient
|
||||
|
||||
A class that represents a MarcSync client.
|
||||
|
||||
<div style={{display: "grid", "grid-template-columns": "repeat(2,minmax(0,1fr))", "box-sizing": "border-box", "border-width": "0", "border-style": "solid", "word-break": "break-word"}}>
|
||||
|
||||
<div style={{"box-sizing": "border-box", "border-width": "0", "border-style": "solid", "word-break": "break-word", "font-weight": "600"}}>
|
||||
METHODS
|
||||
<ul style={{"padding-left": ".5rem", "list-style-type": "disc", "margin-bottom": "1.25rem", "list-style": "none", "box-sizing": "border-box", "border-width": "0", "border-style": "solid", "word-break": "break-word", "font-weight": "500"}}>
|
||||
<li style={{"margin-bottom": ".5rem", "list-style-type": "none"}}>
|
||||
<a style={{"display": "block"}} href="#getVersion">getVersion</a>
|
||||
<a style={{"display": "block"}} href="#fetchCollection">fetchCollection</a>
|
||||
<a style={{"display": "block"}} href="#getCollection">getCollection</a>
|
||||
<a style={{"display": "block"}} href="#createCollection">createCollection</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
## METHODS
|
||||
|
||||
### :getVersion(`clientId:` [number?](https://www.lua.org/pil/2.3.html))
|
||||
Returns the version of the client. If there is no `clientId` specified, it will return the version of the client that is currently running. If there is a `clientId` specified, it will return the version of the client that is running on the specified `clientId`.
|
||||
|
||||
| clientId | Corresponding Client |
|
||||
|----------|----------|
|
||||
| 1 | Roblox Client |
|
||||
| 2 | NodeJS Client |
|
||||
|
||||
### :fetchCollection(`collectionName:` [string](https://www.lua.org/pil/2.4.html))
|
||||
Fetches a collection from the MarcSync API and returns it as a [Collection](./Collection) object.
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
[InvalidAccessToken](../errors/Authorization#InvalidAccessToken) - Thrown when the `accessToken` is invalid.<br/>
|
||||
[CollectionNotFound](../errors/Collection#CollectionNotFound) - Thrown when the collection does not exist.
|
||||
|
||||
:::
|
||||
|
||||
### :getCollection(`collectionName:` [string](https://www.lua.org/pil/2.4.html))
|
||||
Returns a collection from the MarcSync API as a [Collection](./Collection) object. If the collection does not exist, you will get an exception upon trying to use the object.
|
||||
|
||||
### :createCollection(`collectionName:` [string](https://www.lua.org/pil/2.4.html))
|
||||
Creates a new collection in the MarcSync API and returns it as a [Collection](./Collection) object. If the collection already exists, you will get an exception.
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
[InvalidAccessToken](../errors/Authorization#InvalidAccessToken) - Thrown when the `accessToken` is invalid.<br/>
|
||||
[CollectionAlreadyExists](../errors/Collection#CollectionAlreadyExists) - Thrown when the collection already exists.
|
||||
|
||||
:::
|
||||
8
website/docs-marcsync-dev/docs/classes/_category_.json
Normal file
8
website/docs-marcsync-dev/docs/classes/_category_.json
Normal file
@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "MarcSync Classes",
|
||||
"position": 2,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "A list of all classes in the MarcSync library."
|
||||
}
|
||||
}
|
||||
19
website/docs-marcsync-dev/docs/errors/Authorization.md
Normal file
19
website/docs-marcsync-dev/docs/errors/Authorization.md
Normal file
@ -0,0 +1,19 @@
|
||||
# Authorization
|
||||
|
||||
A class that represents authorization exceptions.
|
||||
|
||||
:::info Note
|
||||
|
||||
This class is not meant to be used directly. It is used in the [MarcSyncClient](../classes/MarcSyncClient) class.
|
||||
|
||||
:::
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
Exceptions are cachable, meaning that you can use a `pcall` to catch them.
|
||||
|
||||
:::
|
||||
|
||||
## InvalidAccessToken
|
||||
|
||||
Thrown when the `accessToken` used to create the [MarcSyncClient](../classes/MarcSyncClient) is invalid.
|
||||
23
website/docs-marcsync-dev/docs/errors/Collection.md
Normal file
23
website/docs-marcsync-dev/docs/errors/Collection.md
Normal file
@ -0,0 +1,23 @@
|
||||
# Collection
|
||||
|
||||
A class that represents collection exceptions.
|
||||
|
||||
:::info Note
|
||||
|
||||
This class is not meant to be used directly. It is used in the [MarcSyncClient](../classes/MarcSyncClient) class.
|
||||
|
||||
:::
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
Exceptions are cachable, meaning that you can use a `pcall` to catch them.
|
||||
|
||||
:::
|
||||
|
||||
## CollectionNotFound
|
||||
|
||||
Thrown when the `collectionName` does not exist.
|
||||
|
||||
## CollectionAlreadyExists
|
||||
|
||||
Thrown when the `collectionName` already exists.
|
||||
19
website/docs-marcsync-dev/docs/errors/Entry.md
Normal file
19
website/docs-marcsync-dev/docs/errors/Entry.md
Normal file
@ -0,0 +1,19 @@
|
||||
# Entry
|
||||
|
||||
A class that represents entry exceptions.
|
||||
|
||||
:::info Note
|
||||
|
||||
This class is not meant to be used directly. It is used in the [MarcSyncClient](../classes/MarcSyncClient) class.
|
||||
|
||||
:::
|
||||
|
||||
:::caution Exceptions
|
||||
|
||||
Exceptions are cachable, meaning that you can use a `pcall` to catch them.
|
||||
|
||||
:::
|
||||
|
||||
## InvalidEntryData
|
||||
|
||||
Thrown when the [EntryData](../types/EntryData) is invalid.
|
||||
8
website/docs-marcsync-dev/docs/errors/_category_.json
Normal file
8
website/docs-marcsync-dev/docs/errors/_category_.json
Normal file
@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "MarcSync Exceptions",
|
||||
"position": 4,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "A list of all Exception Classes in the MarcSync library."
|
||||
}
|
||||
}
|
||||
@ -2,46 +2,177 @@
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Tutorial Intro
|
||||
# Getting Started
|
||||
|
||||
Let's discover **Docusaurus in less than 5 minutes**.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Get started by **creating a new site**.
|
||||
|
||||
Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
|
||||
Let's install **MarcSync in less than 5 minutes**.
|
||||
|
||||
### What you'll need
|
||||
|
||||
- [Node.js](https://nodejs.org/en/download/) version 16.14 or above:
|
||||
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
|
||||
- [MarcSync Management Account](https://manage.marcsync.api.marcthedev.it)
|
||||
- Click the "Login with Discord" button and login with your Discord account.
|
||||
- [Roblox Studio](https://create.roblox.com/landing) (Windows or Mac):
|
||||
- [MarcSync Client](https://github.com/MarciiTheDev/marcsync-rbx-client/releases/tag/v1.0.0) Version 1.0.X
|
||||
|
||||
## Generate a new site
|
||||
## Installing the Client
|
||||
|
||||
Generate a new Docusaurus site using the **classic template**.
|
||||
### 1. Open Roblox Studio
|
||||
|
||||
The classic template will automatically be added to your project after you run the command:
|
||||
- Open Roblox Studio and create a new place or open an existing one in which you want to use MarcSync in.
|
||||
|
||||
```bash
|
||||
npm init docusaurus@latest my-website classic
|
||||
### 2. Put in the Client
|
||||
|
||||
:::danger Danger
|
||||
|
||||
Please only use MarcSync in **ONLY SERVER-READABLE PLACES**. This means that you should only use MarcSync in places that are not accessible by players. If you use MarcSync in a place that is accessible by players, they can easily get your token and modify data in your place. If you think your token has been compromised, please generate a new one in the [MarcSync Management Account](https://manage.marcsync.api.marcthedev.it).
|
||||
|
||||
:::
|
||||
|
||||
- Drag and drop the downloaded MarcSync Client into the Explorer window in Roblox Studio.
|
||||
- If you don't see the Explorer window, click the "View" tab and check the "Explorer" box.
|
||||
- You should now see a folder called "MarcSync" in the Explorer window.
|
||||
- Grab the "MarcSync" folder and drag it into the "ServerScriptService" folder.
|
||||
- If you don't see the "ServerScriptService" folder, click the "View" tab and check the "Explorer" box.
|
||||
- You should now see a folder called "MarcSync" in the "ServerScriptService" folder.
|
||||
|
||||
### 3. Configure the Client
|
||||
|
||||
:::caution Warning
|
||||
|
||||
Please make sure to **not** share your token with anyone. This token is used to authenticate your place with the MarcSync API and can be used to modify your place. If you think your token has been compromised, please generate a new one in the [MarcSync Management Account](https://manage.marcsync.api.marcthedev.it).
|
||||
|
||||
:::
|
||||
|
||||
- Open the "MarcSync" folder in the "ServerScriptService" folder.
|
||||
- Open the MarcSyncv1.0 file in the "MarcSync" folder and search for the following lines:
|
||||
|
||||
```lua
|
||||
local tokens = {
|
||||
["exampleToken"] = "AAAAAAAAAA.BBBBBBBBBB.CCCCCCCCCC"
|
||||
}
|
||||
```
|
||||
|
||||
You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
|
||||
- Replace the `AAAAAAAAAA.BBBBBBBBBB.CCCCCCCCCC` with your token from the [MarcSync Management Account](https://manage.marcsync.api.marcthedev.it) and save the file.
|
||||
- Replace the `exampleToken` with a name for your token. This can be anything you want, but it's recommended to use something that describes the place you're using MarcSync in.
|
||||
|
||||
The command also installs all necessary dependencies you need to run Docusaurus.
|
||||
## Implementing MarcSync
|
||||
|
||||
## Start your site
|
||||
:::info Note
|
||||
|
||||
Run the development server:
|
||||
Please make sure to enable HTTP requests in your game settings. You can do this by going to the "Game Settings" tab in Roblox Studio and checking the "Allow HTTP Requests" box. This is required for MarcSync to work.
|
||||
|
||||
```bash
|
||||
cd my-website
|
||||
npm run start
|
||||
:::
|
||||
|
||||
:::danger Danger
|
||||
|
||||
Please only use MarcSync in **ONLY SERVER-READABLE PLACES**. This means that you should only use MarcSync in places that are not accessible by players. If you use MarcSync in a place that is accessible by players, they can easily get your token and modify data in your place. If you think your token has been compromised, please generate a new one in the [MarcSync Management Account](https://manage.marcsync.api.marcthedev.it).
|
||||
|
||||
:::
|
||||
|
||||
### 1. Require MarcSync
|
||||
|
||||
First, we need to require MarcSync in our script. We can do this by adding the following line to the top of our script:
|
||||
|
||||
```lua
|
||||
// highlight-start
|
||||
local MarcSync = require(game:GetService("ServerScriptService"):WaitForChild("MarcSync")["MarcSyncv1.0"])
|
||||
// highlight-end
|
||||
```
|
||||
|
||||
The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
|
||||
### 2. Create a new MarcSync instance
|
||||
|
||||
The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
|
||||
Next, we need to create a new MarcSync instance. We can do this by adding the following line to our script:
|
||||
|
||||
Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
|
||||
```lua
|
||||
local MarcSync = require(game:GetService("ServerScriptService"):WaitForChild("MarcSync")["MarcSyncv1.0"])
|
||||
// highlight-start
|
||||
local ms = MarcSync.new("exampleToken")
|
||||
// highlight-end
|
||||
```
|
||||
|
||||
:::info Note
|
||||
|
||||
Make sure to replace `exampleToken` with the name of your token, like we did in the [Configure the Client](#3-configure-the-client) step.
|
||||
|
||||
:::
|
||||
|
||||
Great! We now have a new MarcSync instance. This instance will be used to communicate with the MarcSync API.
|
||||
|
||||
## Example Usage
|
||||
|
||||
Here is an example of how you can use MarcSync to store a player's playtime in a MarcSync Database.
|
||||
|
||||
```lua
|
||||
local MarcSync = require(game:GetService("ServerScriptService"):WaitForChild("MarcSync")["MarcSyncv1.0"])
|
||||
local ms = MarcSync.new("exampleToken")
|
||||
|
||||
local activityCollection = ms:getCollection("activities")
|
||||
|
||||
local activities = {}
|
||||
|
||||
game:GetService("Players").PlayerAdded:Connect(function(plr)
|
||||
|
||||
local activity = activityCollection:getEntries({
|
||||
["userId"] = plr.UserId
|
||||
})[1]
|
||||
|
||||
if not activity then
|
||||
activity = activityCollection:createEntry({
|
||||
["userId"] = plr.UserId,
|
||||
["playTime"] = 0
|
||||
})
|
||||
end
|
||||
|
||||
-- Not required, but just for a visual example
|
||||
|
||||
local leaderstats = Instance.new("Folder")
|
||||
leaderstats.Name = "leaderstats"
|
||||
leaderstats.Parent = plr
|
||||
|
||||
local playTime = Instance.new("IntValue")
|
||||
playTime.Name = "PlayTime"
|
||||
playTime.Parent = leaderstats
|
||||
playTime.Value = activity:getValue("playTime")
|
||||
|
||||
-- [[ End of visual example ]]
|
||||
|
||||
activities[plr.UserId] = {
|
||||
["activity"] = activity,
|
||||
["joinedAt"] = os.time()
|
||||
}
|
||||
|
||||
end)
|
||||
|
||||
game:GetService("Players").PlayerRemoving:Connect(function(plr)
|
||||
|
||||
activities[plr.UserId].activity:updateValues({
|
||||
["playTime"] = activities[plr.UserId].activity:getValue("playTime") + (os.time() - activities[plr.UserId].joinedAt)
|
||||
})
|
||||
|
||||
end)
|
||||
|
||||
-- Not required, but just for a visual example
|
||||
|
||||
coroutine.wrap(function()
|
||||
while true do
|
||||
task.wait(1)
|
||||
for i,_ in pairs(activities) do
|
||||
game.Players:GetPlayerByUserId(i).leaderstats.PlayTime.Value += 1
|
||||
end
|
||||
end
|
||||
end)()
|
||||
|
||||
-- [[ End of visual example ]]
|
||||
|
||||
```
|
||||
|
||||
:::info Note
|
||||
|
||||
Please make sure to, if you test out try out that example, to replace `exampleToken` with the name of your token, like we did in the [Configure the Client](#3-configure-the-client) step. As well as either creating the `activities` collection via `ms:createCollection("activities")` or replacing `activities` with an already existing collection.
|
||||
|
||||
:::
|
||||
|
||||
:::info Note
|
||||
|
||||
This is just an example of how you can use MarcSync. You can use MarcSync however you want, as long as you follow the [Terms of Service](https://manage.marcsync.api.marcthedev.it/tos.html).
|
||||
|
||||
:::
|
||||
@ -1,8 +0,0 @@
|
||||
{
|
||||
"label": "Tutorial - Basics",
|
||||
"position": 2,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "5 minutes to learn the most important Docusaurus concepts."
|
||||
}
|
||||
}
|
||||
@ -1,23 +0,0 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# Congratulations!
|
||||
|
||||
You have just learned the **basics of Docusaurus** and made some changes to the **initial template**.
|
||||
|
||||
Docusaurus has **much more to offer**!
|
||||
|
||||
Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**.
|
||||
|
||||
Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610)
|
||||
|
||||
## What's next?
|
||||
|
||||
- Read the [official documentation](https://docusaurus.io/)
|
||||
- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config)
|
||||
- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration)
|
||||
- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout)
|
||||
- Add a [search bar](https://docusaurus.io/docs/search)
|
||||
- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase)
|
||||
- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support)
|
||||
@ -1,34 +0,0 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Create a Blog Post
|
||||
|
||||
Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed...
|
||||
|
||||
## Create your first Post
|
||||
|
||||
Create a file at `blog/2021-02-28-greetings.md`:
|
||||
|
||||
```md title="blog/2021-02-28-greetings.md"
|
||||
---
|
||||
slug: greetings
|
||||
title: Greetings!
|
||||
authors:
|
||||
- name: Joel Marcey
|
||||
title: Co-creator of Docusaurus 1
|
||||
url: https://github.com/JoelMarcey
|
||||
image_url: https://github.com/JoelMarcey.png
|
||||
- name: Sébastien Lorber
|
||||
title: Docusaurus maintainer
|
||||
url: https://sebastienlorber.com
|
||||
image_url: https://github.com/slorber.png
|
||||
tags: [greetings]
|
||||
---
|
||||
|
||||
Congratulations, you have made your first post!
|
||||
|
||||
Feel free to play around and edit this post as much you like.
|
||||
```
|
||||
|
||||
A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings).
|
||||
@ -1,57 +0,0 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Create a Document
|
||||
|
||||
Documents are **groups of pages** connected through:
|
||||
|
||||
- a **sidebar**
|
||||
- **previous/next navigation**
|
||||
- **versioning**
|
||||
|
||||
## Create your first Doc
|
||||
|
||||
Create a Markdown file at `docs/hello.md`:
|
||||
|
||||
```md title="docs/hello.md"
|
||||
# Hello
|
||||
|
||||
This is my **first Docusaurus document**!
|
||||
```
|
||||
|
||||
A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello).
|
||||
|
||||
## Configure the Sidebar
|
||||
|
||||
Docusaurus automatically **creates a sidebar** from the `docs` folder.
|
||||
|
||||
Add metadata to customize the sidebar label and position:
|
||||
|
||||
```md title="docs/hello.md" {1-4}
|
||||
---
|
||||
sidebar_label: 'Hi!'
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Hello
|
||||
|
||||
This is my **first Docusaurus document**!
|
||||
```
|
||||
|
||||
It is also possible to create your sidebar explicitly in `sidebars.js`:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
tutorialSidebar: [
|
||||
'intro',
|
||||
// highlight-next-line
|
||||
'hello',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Tutorial',
|
||||
items: ['tutorial-basics/create-a-document'],
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
@ -1,43 +0,0 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Create a Page
|
||||
|
||||
Add **Markdown or React** files to `src/pages` to create a **standalone page**:
|
||||
|
||||
- `src/pages/index.js` → `localhost:3000/`
|
||||
- `src/pages/foo.md` → `localhost:3000/foo`
|
||||
- `src/pages/foo/bar.js` → `localhost:3000/foo/bar`
|
||||
|
||||
## Create your first React Page
|
||||
|
||||
Create a file at `src/pages/my-react-page.js`:
|
||||
|
||||
```jsx title="src/pages/my-react-page.js"
|
||||
import React from 'react';
|
||||
import Layout from '@theme/Layout';
|
||||
|
||||
export default function MyReactPage() {
|
||||
return (
|
||||
<Layout>
|
||||
<h1>My React page</h1>
|
||||
<p>This is a React page</p>
|
||||
</Layout>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page).
|
||||
|
||||
## Create your first Markdown Page
|
||||
|
||||
Create a file at `src/pages/my-markdown-page.md`:
|
||||
|
||||
```mdx title="src/pages/my-markdown-page.md"
|
||||
# My Markdown page
|
||||
|
||||
This is a Markdown page
|
||||
```
|
||||
|
||||
A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page).
|
||||
@ -1,31 +0,0 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Deploy your site
|
||||
|
||||
Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**).
|
||||
|
||||
It builds your site as simple **static HTML, JavaScript and CSS files**.
|
||||
|
||||
## Build your site
|
||||
|
||||
Build your site **for production**:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
The static files are generated in the `build` folder.
|
||||
|
||||
## Deploy your site
|
||||
|
||||
Test your production build locally:
|
||||
|
||||
```bash
|
||||
npm run serve
|
||||
```
|
||||
|
||||
The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/).
|
||||
|
||||
You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**).
|
||||
@ -1,150 +0,0 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Markdown Features
|
||||
|
||||
Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**.
|
||||
|
||||
## Front Matter
|
||||
|
||||
Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
|
||||
|
||||
```text title="my-doc.md"
|
||||
// highlight-start
|
||||
---
|
||||
id: my-doc-id
|
||||
title: My document title
|
||||
description: My document description
|
||||
slug: /my-custom-url
|
||||
---
|
||||
// highlight-end
|
||||
|
||||
## Markdown heading
|
||||
|
||||
Markdown text with [links](./hello.md)
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
Regular Markdown links are supported, using url paths or relative file paths.
|
||||
|
||||
```md
|
||||
Let's see how to [Create a page](/create-a-page).
|
||||
```
|
||||
|
||||
```md
|
||||
Let's see how to [Create a page](./create-a-page.md).
|
||||
```
|
||||
|
||||
**Result:** Let's see how to [Create a page](./create-a-page.md).
|
||||
|
||||
## Images
|
||||
|
||||
Regular Markdown images are supported.
|
||||
|
||||
You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`):
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
## Code Blocks
|
||||
|
||||
Markdown code blocks are supported with Syntax highlighting.
|
||||
|
||||
```jsx title="src/components/HelloDocusaurus.js"
|
||||
function HelloDocusaurus() {
|
||||
return (
|
||||
<h1>Hello, Docusaurus!</h1>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx title="src/components/HelloDocusaurus.js"
|
||||
function HelloDocusaurus() {
|
||||
return <h1>Hello, Docusaurus!</h1>;
|
||||
}
|
||||
```
|
||||
|
||||
## Admonitions
|
||||
|
||||
Docusaurus has a special syntax to create admonitions and callouts:
|
||||
|
||||
:::tip My tip
|
||||
|
||||
Use this awesome feature option
|
||||
|
||||
:::
|
||||
|
||||
:::danger Take care
|
||||
|
||||
This action is dangerous
|
||||
|
||||
:::
|
||||
|
||||
:::tip My tip
|
||||
|
||||
Use this awesome feature option
|
||||
|
||||
:::
|
||||
|
||||
:::danger Take care
|
||||
|
||||
This action is dangerous
|
||||
|
||||
:::
|
||||
|
||||
## MDX and React Components
|
||||
|
||||
[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**:
|
||||
|
||||
```jsx
|
||||
export const Highlight = ({children, color}) => (
|
||||
<span
|
||||
style={{
|
||||
backgroundColor: color,
|
||||
borderRadius: '20px',
|
||||
color: '#fff',
|
||||
padding: '10px',
|
||||
cursor: 'pointer',
|
||||
}}
|
||||
onClick={() => {
|
||||
alert(`You clicked the color ${color} with label ${children}`)
|
||||
}}>
|
||||
{children}
|
||||
</span>
|
||||
);
|
||||
|
||||
This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
|
||||
|
||||
This is <Highlight color="#1877F2">Facebook blue</Highlight> !
|
||||
```
|
||||
|
||||
export const Highlight = ({children, color}) => (
|
||||
<span
|
||||
style={{
|
||||
backgroundColor: color,
|
||||
borderRadius: '20px',
|
||||
color: '#fff',
|
||||
padding: '10px',
|
||||
cursor: 'pointer',
|
||||
}}
|
||||
onClick={() => {
|
||||
alert(`You clicked the color ${color} with label ${children}`);
|
||||
}}>
|
||||
{children}
|
||||
</span>
|
||||
);
|
||||
|
||||
This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
|
||||
|
||||
This is <Highlight color="#1877F2">Facebook blue</Highlight> !
|
||||
@ -1,7 +0,0 @@
|
||||
{
|
||||
"label": "Tutorial - Extras",
|
||||
"position": 3,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 25 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 27 KiB |
@ -1,55 +0,0 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Manage Docs Versions
|
||||
|
||||
Docusaurus can manage multiple versions of your docs.
|
||||
|
||||
## Create a docs version
|
||||
|
||||
Release a version 1.0 of your project:
|
||||
|
||||
```bash
|
||||
npm run docusaurus docs:version 1.0
|
||||
```
|
||||
|
||||
The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.
|
||||
|
||||
Your docs now have 2 versions:
|
||||
|
||||
- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
|
||||
- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs**
|
||||
|
||||
## Add a Version Dropdown
|
||||
|
||||
To navigate seamlessly across versions, add a version dropdown.
|
||||
|
||||
Modify the `docusaurus.config.js` file:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
items: [
|
||||
// highlight-start
|
||||
{
|
||||
type: 'docsVersionDropdown',
|
||||
},
|
||||
// highlight-end
|
||||
],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
The docs version dropdown appears in your navbar:
|
||||
|
||||
|
||||
|
||||
## Update an existing version
|
||||
|
||||
It is possible to edit versioned docs in their respective folder:
|
||||
|
||||
- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`
|
||||
- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`
|
||||
@ -1,88 +0,0 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Translate your site
|
||||
|
||||
Let's translate `docs/intro.md` to French.
|
||||
|
||||
## Configure i18n
|
||||
|
||||
Modify `docusaurus.config.js` to add support for the `fr` locale:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
i18n: {
|
||||
defaultLocale: 'en',
|
||||
locales: ['en', 'fr'],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## Translate a doc
|
||||
|
||||
Copy the `docs/intro.md` file to the `i18n/fr` folder:
|
||||
|
||||
```bash
|
||||
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
|
||||
|
||||
cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md
|
||||
```
|
||||
|
||||
Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French.
|
||||
|
||||
## Start your localized site
|
||||
|
||||
Start your site on the French locale:
|
||||
|
||||
```bash
|
||||
npm run start -- --locale fr
|
||||
```
|
||||
|
||||
Your localized site is accessible at [http://localhost:3000/fr/](http://localhost:3000/fr/) and the `Getting Started` page is translated.
|
||||
|
||||
:::caution
|
||||
|
||||
In development, you can only use one locale at a same time.
|
||||
|
||||
:::
|
||||
|
||||
## Add a Locale Dropdown
|
||||
|
||||
To navigate seamlessly across languages, add a locale dropdown.
|
||||
|
||||
Modify the `docusaurus.config.js` file:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
items: [
|
||||
// highlight-start
|
||||
{
|
||||
type: 'localeDropdown',
|
||||
},
|
||||
// highlight-end
|
||||
],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
The locale dropdown now appears in your navbar:
|
||||
|
||||
|
||||
|
||||
## Build your localized site
|
||||
|
||||
Build your site for a specific locale:
|
||||
|
||||
```bash
|
||||
npm run build -- --locale fr
|
||||
```
|
||||
|
||||
Or build your site to include all the locales at once:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
11
website/docs-marcsync-dev/docs/types/EntryData.md
Normal file
11
website/docs-marcsync-dev/docs/types/EntryData.md
Normal file
@ -0,0 +1,11 @@
|
||||
# EntryData
|
||||
|
||||
EntryData is a type that represents the data of an entry. It is used in the [Collection](../classes/Collection) class to specify the data of an entry, for example.
|
||||
|
||||
## Type Definition
|
||||
|
||||
```typescript
|
||||
type EntryData = {
|
||||
[string]: any
|
||||
}
|
||||
```
|
||||
8
website/docs-marcsync-dev/docs/types/_category_.json
Normal file
8
website/docs-marcsync-dev/docs/types/_category_.json
Normal file
@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "MarcSync Types",
|
||||
"position": 3,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "A list of all Type Classes in the MarcSync library."
|
||||
}
|
||||
}
|
||||
@ -6,20 +6,20 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula');
|
||||
|
||||
/** @type {import('@docusaurus/types').Config} */
|
||||
const config = {
|
||||
title: 'My Site',
|
||||
title: 'Roblox Documentation',
|
||||
tagline: 'Dinosaurs are cool',
|
||||
favicon: 'img/favicon.ico',
|
||||
|
||||
// Set the production url of your site here
|
||||
url: 'https://your-docusaurus-test-site.com',
|
||||
url: 'https://docs.marcsync.dev',
|
||||
// Set the /<baseUrl>/ pathname under which your site is served
|
||||
// For GitHub pages deployment, it is often '/<projectName>/'
|
||||
baseUrl: '/',
|
||||
|
||||
// GitHub pages deployment config.
|
||||
// If you aren't using GitHub pages, you don't need these.
|
||||
organizationName: 'facebook', // Usually your GitHub org/user name.
|
||||
projectName: 'docusaurus', // Usually your repo name.
|
||||
organizationName: 'MarcSync Database', // Usually your GitHub org/user name.
|
||||
projectName: 'marcsync-rbx-client', // Usually your repo name.
|
||||
|
||||
onBrokenLinks: 'throw',
|
||||
onBrokenMarkdownLinks: 'warn',
|
||||
@ -42,7 +42,7 @@ const config = {
|
||||
// Please change this to your repo.
|
||||
// Remove this to remove the "edit this page" links.
|
||||
editUrl:
|
||||
'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
|
||||
'https://github.com/MarciiTheDev/marcsync-rbx-client/tree/main/website/docs-marcsync-dev/',
|
||||
}
|
||||
}),
|
||||
],
|
||||
@ -54,20 +54,20 @@ const config = {
|
||||
// Replace with your project's social card
|
||||
image: 'img/docusaurus-social-card.jpg',
|
||||
navbar: {
|
||||
title: 'My Site',
|
||||
title: 'Roblox Documentation',
|
||||
logo: {
|
||||
alt: 'My Site Logo',
|
||||
alt: 'MarcSync Logo',
|
||||
src: 'img/logo.svg',
|
||||
},
|
||||
items: [
|
||||
{
|
||||
type: 'docSidebar',
|
||||
sidebarId: 'tutorialSidebar',
|
||||
sidebarId: 'docsSidebar',
|
||||
position: 'left',
|
||||
label: 'Tutorial',
|
||||
label: 'Documentation',
|
||||
},
|
||||
{
|
||||
href: 'https://github.com/facebook/docusaurus',
|
||||
href: 'https://github.com/MarciiTheDev/marcsync-rbx-client',
|
||||
label: 'GitHub',
|
||||
position: 'right',
|
||||
},
|
||||
@ -80,7 +80,7 @@ const config = {
|
||||
title: 'Docs',
|
||||
items: [
|
||||
{
|
||||
label: 'Tutorial',
|
||||
label: 'Documentation',
|
||||
to: '/docs/intro',
|
||||
},
|
||||
],
|
||||
@ -88,17 +88,9 @@ const config = {
|
||||
{
|
||||
title: 'Community',
|
||||
items: [
|
||||
{
|
||||
label: 'Stack Overflow',
|
||||
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
|
||||
},
|
||||
{
|
||||
label: 'Discord',
|
||||
href: 'https://discordapp.com/invite/docusaurus',
|
||||
},
|
||||
{
|
||||
label: 'Twitter',
|
||||
href: 'https://twitter.com/docusaurus',
|
||||
href: 'https://discord.com/invite/pyysgrUeYE',
|
||||
},
|
||||
],
|
||||
},
|
||||
@ -107,16 +99,17 @@ const config = {
|
||||
items: [
|
||||
{
|
||||
label: 'GitHub',
|
||||
href: 'https://github.com/facebook/docusaurus',
|
||||
href: 'https://github.com/MarciiTheDev/marcsync-rbx-client',
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
|
||||
copyright: `Copyright © ${new Date().getFullYear()} MarcSync Database. Built with Docusaurus.`,
|
||||
},
|
||||
prism: {
|
||||
theme: lightCodeTheme,
|
||||
darkTheme: darkCodeTheme,
|
||||
additionalLanguages: ['lua']
|
||||
},
|
||||
}),
|
||||
};
|
||||
|
||||
@ -14,7 +14,7 @@
|
||||
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
|
||||
const sidebars = {
|
||||
// By default, Docusaurus generates a sidebar from the docs folder structure
|
||||
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
|
||||
docsSidebar: [{type: 'autogenerated', dirName: '.'}],
|
||||
|
||||
// But you can create a sidebar manually
|
||||
/*
|
||||
|
||||
@ -0,0 +1,22 @@
|
||||
import siteConfig from '@generated/docusaurus.config';
|
||||
export default function prismIncludeLanguages(PrismObject) {
|
||||
const {
|
||||
themeConfig: {prism},
|
||||
} = siteConfig;
|
||||
const {additionalLanguages} = prism;
|
||||
// Prism components work on the Prism instance on the window, while prism-
|
||||
// react-renderer uses its own Prism instance. We temporarily mount the
|
||||
// instance onto window, import components to enhance it, then remove it to
|
||||
// avoid polluting global namespace.
|
||||
// You can mutate PrismObject: registering plugins, deleting languages... As
|
||||
// long as you don't re-assign it
|
||||
globalThis.Prism = PrismObject;
|
||||
additionalLanguages.forEach((lang) => {
|
||||
// eslint-disable-next-line global-require, import/no-dynamic-require
|
||||
require(`prismjs/components/prism-${lang}`);
|
||||
});
|
||||
|
||||
require('prismjs/components/prism-lua');
|
||||
|
||||
delete globalThis.Prism;
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user