diff --git a/content/docs/core/command-settings.md b/content/docs/core/command-settings.md index 97b3943..bdd2782 100644 --- a/content/docs/core/command-settings.md +++ b/content/docs/core/command-settings.md @@ -26,14 +26,14 @@ prefix was instead `?`, one would use `?remindme ...`, and so on. Slash commands are always triggered using the `/` character and hence do not depend on the prefix configured here. -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Mention as a Command Prefix" icon="outline/rocket" >}} In addition to the command prefix, you can trigger YAGPDB commands by pinging the bot at the start of your message. This is helpful if you forget your prefix, as sending `@YAGPDB.xyz prefix` will recall it. {{< /callout >}} -{{< callout context="caution" title="Flags and Switches" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Caution: Flags and Switches" icon="outline/alert-triangle" >}} Flags and switches are **_not_** affected by your prefix setting. @@ -52,21 +52,18 @@ where the `raw` switch is still spelled `-raw`, not `?raw`. Command overrides are considered in the following order, with settings applied at later steps overwriting earlier ones: 1. If the _All commands enabled_ setting is not checked, all commands are initially disabled (otherwise enabled.) -2. General restrictions configured in _Global Settings_ are then applied, base restrictions before command-specific restrictions. +2. General restrictions configured in _Global Settings_ are then applied, base restrictions before command-specific + restrictions. 3. Channel-specific restrictions (_Override #1_, _Override #2_, ...) are applied analogously. -The order above trickles down from least specific to most specific, prioritizing the most specific setting -- an analogy +The order above trickles down from least specific to most specific, prioritizing the most specific setting---an analogy for developers would be CSS's cascading rules. -{{< callout context="note" title="Example" icon="outline/info-circle" >}} - Though perhaps confusing at first, the priority order above is designed to make common configurations trivial. For -instance, to disable all but a specific command -- say the `remindme` command -- one can simply disable the _All +instance, to disable all but a specific command---say the `remindme` command---one can simply disable the _All commands enabled_ option and then create a command override that enables only `remindme`. This is possible as command overrides are applied after the _All commands enabled_ setting. -{{< /callout >}} - ## Options ### Common Options @@ -80,13 +77,11 @@ Clicking on either of these options (**3**,**4**) opens a drop-down menu with al Select as many as you wish. YAGPDB will then either require all members to have any of these roles in order to run commands, or completely ignore members with any of the ignored roles, server admins and owners included. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Priority of Ignored vs. Required Roles" icon="outline/info-circle" >}} YAGPDB was raised well and honors a "no" when told "no". In other words, ignored roles take precedence over required roles. -This is a relatively common trip-hazard, so take great care when you set up both required and ignored roles. - {{< /callout >}} #### Autodelete Trigger / Response Interval @@ -101,12 +96,8 @@ If 10 seconds are not enough, or too long, feel free to adjust as you see fit; t These options are only available for channel overrides (**8**). To add a new one, head to the _New channel override_ tab on the command settings page. -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} - You must select at least one channel or category; otherwise, the settings of the override will not be applied. -{{< /callout >}} - #### Channels With this setting, you can select individual channels to apply the override to. Select as many as you wish. diff --git a/content/docs/custom-commands/commands.md b/content/docs/custom-commands/commands.md index 0d38f51..ff23062 100644 --- a/content/docs/custom-commands/commands.md +++ b/content/docs/custom-commands/commands.md @@ -30,7 +30,7 @@ Edit this to change the output of the custom command {{.CCID}}! Each custom command is assigned a unique incrementing ID, which cannot be modified after creation. -{{< callout context="tip" title="Troubleshooting" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Troubleshooting" icon="outline/rocket" >}} ![Empty CC Discord Messages](empty_cc_1.png) @@ -79,21 +79,13 @@ Selecting a group allows you to edit it. Changes must be saved (**11**) to take Using role/channel restrictions, it is possible to set conditions on which users can trigger a custom command. Specifically, whitelisted roles or channels are required to run the command, whereas blacklisted roles or channels -cannot use the command at all. +cannot use the command at all. These role restrictions are unrelated to member permissions. Having `Administrator` +permissions will not override these restrictions. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Priority of Ignored vs. Required Roles" icon="outline/info-circle" >}} YAGPDB was raised well and honors a "no" when told "no". In other words, blacklists take precedence over whitelists. -This is a relatively common trip-hazard, so take great care when you set up both whitelists and blacklists. - -{{< /callout >}} - -{{< callout context="note" title="Note" icon="outline/info-circle" >}} - -Role restrictions are unrelated to member permissions. Having `Administrator` permissions will not override these -restrictions. - {{< /callout >}} ## Editing a Custom Command @@ -125,7 +117,7 @@ commands like `customcommands` accept a CC ID as an argument. Within a command response, the ID may be retrieved using the `{{ .CCID }}` template. -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Deleting is Irreversible" icon="outline/alert-octagon" >}} Deleting a custom command does not allow its ID to be reassigned. If you delete a CC, its ID is lost forever. @@ -187,7 +179,7 @@ Reactions to a message will trigger the command. Can specify **Added Only**, **Removed Only**, or **Both** to restrict which types of Reactions will trigger the command. -{{< callout context="tip" title="Filtering Emojis" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Filtering Emojis" icon="outline/rocket" >}} You cannot specify which emojis the command will trigger on. If you'd like to limit which emojis run the code, you will need to write that code yourself in the response. @@ -232,12 +224,8 @@ When editing an interval command, a **Run Now** button appears at the bottom of long as the command is not disabled and a channel is selected. Running an interval command using this button reschedules all subsequent runs based off the current time. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} - You must specify a channel to run interval commands in even if the command doesn't output a message. -{{< /callout >}} - ##### Component [In-depth Interactions Guide](/docs/reference/custom-interactions) @@ -282,13 +270,6 @@ getting data from users, sending messages to other channels, and more. Visit the {{< link-card href="/docs/reference/templates/syntax-and-data" description="Templates" target="_blank" >}} -{{< callout context="tip" title="Keeping your code safe" icon="outline/rocket" >}} - -It is recommended to save local copies of your custom commands. There is no way to recover deleted or overwritten CCs. -Use an editor like **Vim**, **VS Code**, or **Notepad++** for the best coding experience. - -{{< /callout >}} - ### Custom Command Group Dropdown selection (**9**) to change which command group the command is in. Select `None` to ungroup the command. @@ -319,7 +300,7 @@ not send a response. It also increases if the command is run via `execCC`. The run count will not increase if the user who ran the command did not pass the restrictions. -{{< callout context="tip" title="Troubleshooting" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Troubleshooting" icon="outline/rocket" >}} If your command fails to run, check the run count. If the run count increases when you attempt to run the command, the issue is with your code. Otherwise, the issue may be with YAGPDB's permissions in your server, or improperly configured @@ -359,7 +340,7 @@ A custom command **will not save** if there is an error in your input. Examples If you save a command with an interval trigger which has never been run, it will run immediately upon saving. -{{< callout context="tip" title="Keeping your code safe" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Keeping Your Code Safe" icon="outline/rocket" >}} It is recommended to code your custom command using a local editor on your device. You will not be able to save your code on the dashboard if there are syntax errors in your code. Use an editor like **Vim**, **VS Code**, or **Notepad++** @@ -367,7 +348,7 @@ for the best coding experience. {{< /callout >}} -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Remember to Save" icon="outline/alert-octagon" >}} Custom commands do not autosave. diff --git a/content/docs/fun/soundboard.md b/content/docs/fun/soundboard.md index 0a16f35..d3ab0da 100644 --- a/content/docs/fun/soundboard.md +++ b/content/docs/fun/soundboard.md @@ -19,12 +19,13 @@ Choose to require users to have a role in order to play this sound. ### Upload file -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="note" title="Note: Choose Either URL or File Upload" icon="outline/info-circle" >}} Do **not** fill in the URL if you are going uploaded from local files, and vice versa. {{< /callout >}} + You have two options to upload sounds: - Upload with local files @@ -32,26 +33,21 @@ You have two options to upload sounds: #### Upload with local files -Click on _Choose file_ and \_\_ select an audio file to upload. All types of sound files, including videos with sound -tracks, are supported. +Click on _Choose file_ and select an audio file to upload. All types of sound files, including videos with soundtracks, +are supported. #### Specify a URL -You can also specify a sound URL instead of uploading one. - -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +You can also specify a sound URL instead of uploading one. -This has to be the direct link to the media file, and not a YouTube link. A direct link should end with`.mp3`(or other -relevant audio/video type), such as -[http://soundboard.panictank.net/AIRHORN.mp3](http://soundboard.panictank.net/AIRHORN.mp3). - -{{< /callout >}} +This has to be the direct link to the media file, and not, for example, a YouTube Video link. A direct link should end +with `.mp3` (or other relevant audio/video type), such as . ### Finish Click on _Upload/Download_ after you are done with the previous steps. You should see a _Success_ notification when the -upload is completed. Check the status of the sound under _Existing sounds_. \__ Wait for several minutes, and press -\_Save_ again if the status does not show _Ready_. +upload is completed. Check the status of the sound under _Existing sounds_. Wait for several minutes, and press +_Save_ again if the status does not show _Ready_. ![An example of a successfully uploaded sound](example_soundboard.png) diff --git a/content/docs/moderation/advanced-automoderator/conditions.md b/content/docs/moderation/advanced-automoderator/conditions.md index daa0530..ba8d8c0 100644 --- a/content/docs/moderation/advanced-automoderator/conditions.md +++ b/content/docs/moderation/advanced-automoderator/conditions.md @@ -21,7 +21,7 @@ By extension, these conditions are also available as ruleset scoped conditions. All conditions have to be met in order for a rule to execute — that is, the conditions are combined according to the logical AND operator. -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Mutual Exclusivity" icon="outline/alert-octagon" >}} Ensure that the conditions you set are not in conflict or mutually exclusive, as this will cause your rule to never trigger. diff --git a/content/docs/moderation/logging.md b/content/docs/moderation/logging.md index 86324ff..a682498 100644 --- a/content/docs/moderation/logging.md +++ b/content/docs/moderation/logging.md @@ -9,7 +9,7 @@ limited number of deleted messages. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Not a Logging Bot" icon="outline/info-circle" >}} YAGPDB IS NOT A LOGGING BOT. @@ -24,7 +24,7 @@ The log is accessible on YAGPDB's website for later viewing. It saves message ti User ID, and the message itself. If a message contains an attachment, the attachment URL is logged. If a message contains an embed, it is serialized and saved in JSON format. -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Maximum Log Retention" icon="outline/alert-octagon" >}} Message logs on the official YAGPDB instance will be automatically deleted after 30 days of their creation. diff --git a/content/docs/moderation/moderation-tools.md b/content/docs/moderation/moderation-tools.md index 9bfb7a7..693c7c6 100644 --- a/content/docs/moderation/moderation-tools.md +++ b/content/docs/moderation/moderation-tools.md @@ -185,7 +185,7 @@ mute tab on the control panel. [Unmute Command Syntax](/docs/core/all-commands#unmute) -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Discord Permission Precedence" icon="outline/alert-octagon" >}} Within a server channel's permission overrides, allowing a permission to a specific role or user supersedes disallowing a permission to a specific role. This means if you grant Role X the permission to send messages in a channel and @@ -199,7 +199,7 @@ when configuring other roles' permission overrides. {{< /callout >}} -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Unmute Author After Duration Expired" icon="outline/info-circle" >}} If you set a duration for the mute, the bot will unmute the user after the specified duration. When this occurs, it appears as an unmute action taken by YAGPDB in your mod log, regardless of which moderator initially muted the user. @@ -237,7 +237,7 @@ field in the ban tab on the control panel which enables automatic deletion when [Unban Command Syntax](/docs/core/all-commands#unban) -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Unban Author After Duration Expired" icon="outline/info-circle" >}} If you set a duration for the ban, the bot will unban the user after the specified duration. When this occurs, it appears as an unban action taken by YAGPDB in your mod log, regardless of which moderator initially banned the user. @@ -276,7 +276,7 @@ You may optionally send warnings to the mod log, this is enabled in the warnings [TopWarnings Command Syntax](/docs/core/all-commands#topwarnings) - Shows ranked list of warnings on the server, allowing you to turn misbehavior into a fun minigame for your server members. -{{< callout context="tip" title="Taking Action on Warn Count" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Taking Action on Warn Count" icon="outline/rocket" >}} Some users prescribe an "x warnings => mute/kick/ban" rule for their servers. To have YAGPDB automatically take action based on warning count, you can take advantage of the template scripting within the warning DM. diff --git a/content/docs/moderation/verification.md b/content/docs/moderation/verification.md index cd7d1f6..b4c2824 100644 --- a/content/docs/moderation/verification.md +++ b/content/docs/moderation/verification.md @@ -16,7 +16,7 @@ This is accomplished by sending new members a customizable DM (which employs [te containing a unique link to verify, tied to their User ID. This link takes them to a customizable verification page with a CAPTCHA challenge. Once completed, the User ID is assigned the verified role. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Verified Role" icon="outline/info-circle" >}} You must assign a "Verified Role" on the Verification page in the control panel. The plugin will not function if no role is selected. @@ -46,7 +46,7 @@ You can customize both messages in the Verification page on the control panel. Verification scripts provide `.Link` as additional dot context data. This is the unique verification link the user must visit to verify. -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: DMs may not be Received" icon="outline/alert-octagon" >}} If a user has disabled DMs from server members by default, upon joining your server YAGPDB will fail to send a verification DM to the user. It is recommended that you inform your new members about this possibility and how to fix it @@ -74,7 +74,7 @@ Logged events are: ## Alt Detection -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Disabled on Official Instance" icon="outline/info-circle" >}} Alt Detection is currently disabled on the official instance of YAGPDB hosted by Botlabs. These features will not function on the official bot. diff --git a/content/docs/notifications/general.md b/content/docs/notifications/general.md index 0c9b5c5..d5bc0fd 100644 --- a/content/docs/notifications/general.md +++ b/content/docs/notifications/general.md @@ -30,7 +30,7 @@ Write a message that you want the bot to send to the user via DM whenever someon Choose what channel you want the bot to announce the topic change from a specific channel or the channel that the topic was changed in. -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Custom Command Syntax" icon="outline/rocket" >}} Custom command templates are supported for usage in all the notification feeds provided. diff --git a/content/docs/notifications/reddit.md b/content/docs/notifications/reddit.md index a3bd0cd..f408875 100644 --- a/content/docs/notifications/reddit.md +++ b/content/docs/notifications/reddit.md @@ -8,12 +8,6 @@ Get notifications from your favorite subreddits directly in your Discord server. -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} - -Fast Reddit feeds to the **top 10 subreddits** are disabled, due to being too spammy for YAGPDB's current system. - -{{< /callout >}} - ## Reddit Feed ![Small showcase of the Reddit feeds interface.](./reddit.png) diff --git a/content/docs/notifications/streaming.md b/content/docs/notifications/streaming.md index 58e9311..7dc4bf5 100644 --- a/content/docs/notifications/streaming.md +++ b/content/docs/notifications/streaming.md @@ -9,14 +9,14 @@ Let everyone know that someone is currently streaming. ### Streaming Feed -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Announcements may not Post" icon="outline/info-circle" >}} There are currently some issues with the streaming announcement, and it may not always give the announcement. It will however, always assign the streamer role. {{< /callout >}} -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Automatic Role Removal" icon="outline/alert-octagon" >}} The streaming role will be **automatically removed** from a member that is not streaming if it is given manually, so be careful! If YAGPDB is removing member's roles without apparent reason, this may well be the cause. diff --git a/content/docs/notifications/youtube.md b/content/docs/notifications/youtube.md index bb5f3e1..94663c2 100644 --- a/content/docs/notifications/youtube.md +++ b/content/docs/notifications/youtube.md @@ -10,22 +10,8 @@ Get notifications from your favorite YouTubers directly in your Discord server. ## YouTube Feed -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} - -Do **NOT** fill in both the Channel ID and the Channel URL. - -- There may be up to 5-15 minutes of delay for the bot to announce the video after it gets posted. -- The bot will only announce the video if it's public. - -{{< /callout >}} - -![Showcase of the YouTube feed interface.](./youtube.png) - -To get notifications from a YouTube channel, simply go to the YouTuber's channel and input either the ID or the Username in their respective field of the followings: - -- YouTube Channel ID - -- YouTube Channel Username +Fill in either the YouTube Channel ID, or a Channel URL, not both. The bot will automatically extract the Channel ID +from the URL. If your channel looks like this `youtube.com/user/h3h3Productions` then you would go into the username line and type in h3h3Productions. @@ -33,6 +19,12 @@ in h3h3Productions. If your channel looks like this `youtube.com/channel/UCt-ERbX-2yA6cAqfdKOlUwQ` then you would go into the ID line and type in UCt-ERbX-2yA6cAqfdKOlUwQ. +There may be up to 5--15 minutes of delay for the bot to announce the video after it gets posted, if and only if it is +publicly available. Should you publish your videos as "Members first", the bot will post an announcement once it is +available to the public. + +![Showcase of the YouTube feed interface.](./youtube.png) + You can change the channel that the notifications are posted to via the dropdown menu. You can also mention everyone by clicking the checkbox under the dropdown menu that says Mention everyone. diff --git a/content/docs/reference/custom-command-examples.md b/content/docs/reference/custom-command-examples.md index dbd5154..6e398ed 100644 --- a/content/docs/reference/custom-command-examples.md +++ b/content/docs/reference/custom-command-examples.md @@ -8,7 +8,7 @@ Prebuilt custom commands for use as a learning reference. -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Out of Date" icon="outline/alert-octagon" >}} Note: This page is no longer updated with the latest versions of codes/commands. If you plan to copy paste codes for your server, see [this website](https://yagpdb-cc.github.io) which is frequently updated with new community-contributed @@ -16,20 +16,15 @@ commands. {{< /callout >}} -{{< callout context="note" title="Note" icon="outline/info-circle" >}} - This isn't the actual page about custom commands. A brief overview about custom commands can be found in the -[Custom Commands documentation](/docs/custom-commands/commands). Please take notice, some of examples presented here are not up to -date with current capabilities of YAGPDB. Please visit our [support server](https://discord.gg/0vYlUK2XBKldPSMY) for -newer solutions. - -{{< /callout >}} +[Custom Commands documentation](/docs/custom-commands/commands). Please take notice, some of examples presented here are +not up to date with current capabilities of YAGPDB. Please visit our [support server](/discord) for newer solutions. ### Controlled randomizer example YAGPDB has a built-in random response system for custom commands, but sometimes you may want to control the chances for certain responses to occur. You can do this by creating a singular response and creating a variable with randInt. Then -use an if else if statement like this to print out your desired output. +use an if-else-if statement like this to print out your desired output. ```yag {{$var := randInt 100}} diff --git a/content/docs/reference/custom-embeds.md b/content/docs/reference/custom-embeds.md index f14495c..3c8f5f4 100644 --- a/content/docs/reference/custom-embeds.md +++ b/content/docs/reference/custom-embeds.md @@ -8,14 +8,14 @@ A guide to creating custom embeds in various contexts across YAGPDB. -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Embed Limitations" icon="outline/alert-octagon" >}} Embeds have limits, summarized in [Discord channel documentation](https://discord.com/developers/docs/resources/channel#embed-object-embed-limits). {{< /callout >}} -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Custom Commands use Custom Syntax" icon="outline/info-circle" >}} Custom Embeds with the `-customembed` command don't work in custom commands. If you want to know how you can use embeds in custom commands, scroll down to [Embeds in Custom Commands](#embeds-in-custom-commands). @@ -24,12 +24,12 @@ in custom commands, scroll down to [Embeds in Custom Commands](#embeds-in-custom ## The `customembed` command -One method of sending an embed with YAGPDB is using the command `customembed` (or for short, `ce`). +One method of sending an embed with YAGPDB is using the command `customembed` (or for short, `ce`). ### Create embeds by hand YAGPDB accepts embeds in JSON following the rules of [this -format](https://discordapp.com/developers/docs/resources/channel#embed-object). +format](https://discordapp.com/developers/docs/resources/channel#embed-object). There, we'll take a look at the **Embed Objects**. You can add a value to each of these objects. A very simple embed would look like this: @@ -47,7 +47,7 @@ curly brace. Then we have the name of the object (title) and the value of it (Th commas. After that we have the same thing again, but for the description. In the end we close the object (embed) with another curly brace. -You can add the multiple objects to this, but keep in mind that Discord limits your message to 2000 characters. +You can add the multiple objects to this, but keep in mind that Discord limits your message to 2000 characters. #### The syntax of JSON @@ -71,7 +71,7 @@ false statements). You can play around with this a bit. Creating embeds with a generator can be more difficult if you don't need any difficult features. If you want your embed to be super shiny, you can use [this embed generator](https://leovoel.github.io/embed-visualizer/). YAGPDB does not use -the first part of its code, so you have to remove the following: +the first part of its code, so you have to remove the following: ````javascript { @@ -85,13 +85,7 @@ and the last curly brace (`}`). After this you can just copy and paste it into D ## Embeds in Custom Commands -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} - -Embeds in custom commands are a little more difficult. Also, there is no generator that you could use for this. **Please only proceed if you have a good amount of knowledge about custom commands and templates in general.** - -{{< /callout >}} - -To start off, we'll take a look at this example and break it down: +Embeds in custom commands are a little more involved. To start off, we'll take a look at this example and break it down: ```yag {{ $embed := cembed "title" "This is my title" "description" "This is my description." }} @@ -104,13 +98,14 @@ braces. This makes it a bit clearer as your embed can get difficult to read. Aft define everything one after the other ("`name`" "`value`" et cetera). Now we use the objects for discord embeds from the [developer page](https://discordapp.com/developers/docs/resources/channel#embed-object) again. So far, so good. In the end we send our embed with the sendMessage template. `nil` sends it in the same channel, but you could also replace it -with a channel name or ID (or send the embed with sendDM as a direct message). +with a channel name or ID (or send the embed with sendDM as a direct message). Next, we'll take a look at this more lavish example: -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Indentation is Your Friend" icon="outline/info-circle" >}} -To make your code readable, especially for large embeds, **indents** may be used, as YAGPDB's templating system allows this sort of formatting. +To make your code readable, especially for large embeds, **indents** may be used, as YAGPDB's templating system allows +this sort of formatting. {{< /callout >}} @@ -157,11 +152,11 @@ To make your code readable, especially for large embeds, **indents** may be used In this example, we can ignore lines 1 to 5. I'm just defining some variables there which I am later using in my embed. One thing to notice is the two ways of getting user's avatar URL for variables `$avatar` and `$botAvatar`. Line 7 starts with our already known definition of the embed. Then I start with the first object, the title. Notice how I use `print` -to join two strings (text snippets) together.\ -\ +to join two strings (text snippets) together. + Next, we have the description. We can use markdown of Discord in here. After that object, I define the color. The color is given as integer and you can convert a hex color to it using -[BinaryHex Converter](https://www.binaryhexconverter.com/hex-to-decimal-converter), for example.. +[BinaryHex Converter](https://www.binaryhexconverter.com/hex-to-decimal-converter), for example. Up next, I have added some fields. This is a bit more difficult, but doable if you have understood it once. Let's break it down in this example: @@ -183,10 +178,10 @@ template. After this we just have to send the embed using `SendMessage` or `Send ![Result of Embedding with Custom Command](embed_custom_command_result.png) -### Display an image +### Display an image -You can display an image by simply pasting the link to it in the response, or by doing it fancy this way:\ -(make sure to replace the link with your own image ;)) +You can display an image by simply pasting the link to it in the response, or by doing it fancy this way +(make sure to replace the link with your own image): Trigger type: command trigger: `imageembed` @@ -236,12 +231,4 @@ This generates the following embed: ![SimpleEmbed Result](simpleembed_example.png) -You can play around with this command a bit, it's really easy to use. - -{{< callout context="note" title="Note" icon="outline/info-circle" >}} - -Simple embeds can be used in custom commands: - -`{{execAdmin "se" "-desc" "This is my description"}}` - -{{< /callout >}} +You can play around with this command a bit, it's really easy to use. diff --git a/content/docs/reference/custom-interactions.md b/content/docs/reference/custom-interactions.md index 7ab5f76..7a3d108 100644 --- a/content/docs/reference/custom-interactions.md +++ b/content/docs/reference/custom-interactions.md @@ -8,12 +8,12 @@ Buttons, Modals, Select Menus, Ephemeral Messages, and more! -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Advanced Topic" icon="outline/alert-octagon" >}} Use of interactions within YAGPDB is an advanced topic; you will need a thorough understanding of YAGPDB's scripting language before learning interactions. -We have a [comprehensive learning course](https://learn.yagpdb.xyz) for you to get started. +We have a [comprehensive learning course](/learn/welcome/introduction) for you to get started. {{< /callout >}} @@ -123,7 +123,7 @@ ID which can trigger a custom command. ##### Custom IDs -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Unique Custom ID" icon="outline/info-circle" >}} Multiple buttons and menus can not have the same custom ID in one message. @@ -234,7 +234,7 @@ Setting default values in these select menus is a more involved process than for ![The above mentionable menu with default options selected](mentionable_menu_with_defaults.png) -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Correct Data Type" icon="outline/info-circle" >}} The `default_values` `id`s must be `string`s, not `int64`s. Note how in the above example, `$adminRoleID := "1210128415689285642"` defining it as a string, as opposed to `$adminRoleID := 1210128415689285642` which would define @@ -272,7 +272,7 @@ This gives us a select menu which we can only select guild announcement and guil Now, let's add some more buttons. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Button Type Limitations" icon="outline/info-circle" >}} Buttons with the "link" style cannot have a Custom ID, and instead require a URL field. diff --git a/content/docs/reference/templates/functions.md b/content/docs/reference/templates/functions.md index 81477e0..30e841c 100644 --- a/content/docs/reference/templates/functions.md +++ b/content/docs/reference/templates/functions.md @@ -515,13 +515,9 @@ To cancel such a scheduled custom command before it runs, use [cancelScheduledUn ## Interactions -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} - Use of interactions within YAGPDB is an advanced topic; the documentation should be used only as reference. To learn about using interactions, [see here](/docs/reference/custom-interactions). -{{< /callout >}} - ### Interaction Responses - Only one interaction response may be sent to each interaction. @@ -1634,7 +1630,7 @@ Reports whether the specified target has the specified role name (case-insensiti ## String manipulation -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: RegEx Limitations" icon="outline/info-circle" >}} All regexp functions are limited to 10 different pattern calls per CC. @@ -1952,11 +1948,11 @@ Returns the UTC time corresponding to the given UNIX time, measured in seconds s Returns the ISO 8601 week number in which the time occurs, ranging between 1 and 53. Jan 01 to Jan 03 of year n might belong to week 52 or 53 of year n-1, and Dec 29 to Dec 31 might belong to week 1 of year n+1. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Discord Timestamp Formatting" icon="outline/info-circle" >}} Discord Timestamp Styles referenced on -[Discord message documentation](https://discord.com/developers/docs/reference#message-formatting-timestamp-styles) can be done using `print` -function e.g. +[Discord message documentation](https://discord.com/developers/docs/reference#message-formatting-timestamp-styles) +can be done using the `print` function: `{{print ""}}` for "Long Date/Time" formatting. @@ -2114,7 +2110,7 @@ All keys are optional, but the Discord API will reject completey empty embeds, s - `icon_url`: a small icon to display to the left of the footer's text - `timestamp`: a (static) timestamp to display to the right of the footer's text -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Custom Commands Embed Generator" icon="outline/rocket" >}} To help you get used to the embed structure in custom commands, check out , a community-made embed visualizer for YAGPDB's custom command system. @@ -2132,9 +2128,8 @@ Creates a new ticket associated to the specified author with given topic. - `author`: the member to associate this ticket with. - `topic`: the topic of this ticket. Must be a string. -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Dependency on Ticketing System" icon="outline/alert-triangle" >}} - For this function to work correctly, the ticketing system must be enabled. {{< /callout >}} diff --git a/content/docs/reference/templates/syntax-and-data.md b/content/docs/reference/templates/syntax-and-data.md index 69b6f6a..a9e5f7c 100644 --- a/content/docs/reference/templates/syntax-and-data.md +++ b/content/docs/reference/templates/syntax-and-data.md @@ -14,33 +14,13 @@ All available data that can be used in YAGPDB's templating "engine" which is sli stdlib text/template package; more in depth and info about actions, pipelines and global functions like `printf, index, len,`etc > [https://golang.org/pkg/text/template/](https://golang.org/pkg/text/template/) . This section is meant to be a concise and to the point reference document for all available templates/functions. **Functions** are covered -in [Function documentation](/docs/reference/templates/functions). For detailed explanations and syntax guide refer to the [learning -resource](https://learn.yagpdb.xyz/). +in [Function documentation](/docs/reference/templates/functions). For detailed explanations and a syntax guide, please +refer to the [learning resource](/learn/welcome/introduction). -**Legend**: at current state this is still prone to formatting errors, but everything in a `code block` should refer to -a function, parts of a template's action-structure or output returned by YAGPDB; single word/literal-structure in -_italics_ refers to type. Methods and fields (e.g. .Append, .User) are usually kept in standard formatting. If argument -for a function is optional, it's enclosed in parenthesis `( )`. If there are many optional arguments possible, it's -usually denoted by 3-dot `...`ellipsis. +{{< callout context="note" title="Note: Disable \"Smart\" Quotes" icon="outline/info-circle" >}} -\ -If functions or methods are denoted with an accent, tilde \~, they are not yet deployed in actual YAGPDB bot or have -been disabled in main bot, but are in master code branch. - -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} - -**Always put curly brackets around the data and "actions you perform" you want to formulate as a template** like -this:`{{.User.Username}}` - -This `{{ ... }}` syntax of having two curly brackets aka braces around context is necessary to form a template's control -structure also known as an action with methods and functions stated below. - -{{< /callout >}} - -{{< callout context="note" title="Note" icon="outline/info-circle" >}} - -Templating system uses standard ASCII quotation marks:\ -0x22 > `"` for straight double quotes, 0x27 > `'`for apostrophes and 0x60 `` ` `` for backticks/back quotes; so make +Templating system uses standard ASCII quotation marks: +`"` for straight double quotes, `'` for apostrophes or single quotes and`` ` `` for backticks/back quotes; so make sure no "smart-quotes" are being used. The difference between back quotes and double quotes in string literals is covered in @@ -51,38 +31,34 @@ the [Go Language Specification](https://go.dev/ref/spec#String_literals). ## The Dot and Variables The dot (also known as cursor) `{{ . }}` encompasses all active data available for use in the templating system, in -other words it always refers to current context. \ -\ +other words it always refers to current context. + For example .User is a Discord User object/structure of current context, meaning the triggering user. To get user object for other users, functions `getMember`, `userArg` would help. Same meaning of object/struct applies to other **Fields** with dot prefix. If it is mentioned as a **Method** (for example, .Append for type _cslice_) or as a field on a struct (for example, .User.Bot) then it can not be used alone in template context and always belongs on a parent value. That is, `{{.Bot}}` would return `` whereas `{{.User.Bot}}` returns _bool_ true/false. Another good example is .Reaction.Emoji.MessageFormat, here you can use .MessageFormat every time you get emoji structure of type -_discordgo.Emoji_, either using reaction triggers or for example .Guild.Emojis.\ -\ +_discordgo.Emoji_, either using reaction triggers or for example .Guild.Emojis. + From official docs > "Execution of the template walks the structure and sets the cursor, represented by a period `.` and called "dot", to the value at the current location in the structure as execution proceeds." All following fields/methods/objects like User/Guild/Member/Channel etc are all part of that dot-structure and there are some more in tables below. For commenting something inside a template, use this syntax: `{{/* this is a comment */}}`. May contain newlines. -Comments do not nest and they start and end at the delimiters. +Comments do not nest, and they start and end at the delimiters. -To trim spaces use hyphens after/before curly brackets, for example >`{{- /* this is a multi-line` \ -`comment with whitespace trimmed from preceding and following text */ -}}` \ -Using`{{- ... -}}` is also handy inside`range` actions, because whitespaces and newlines are rendered there as output.\ -\ `$` has a special significance in templates, it is set to the [starting value of a dot](https://golang.org/pkg/text/template/#hdr-Variables). This means you have access to the global context from anywhere - e.g., inside `range`/`with` actions. `$` for global context would cease to work if you redefine it inside -template, to recover it `{{ $ := . }}`.\ -\ +template, to recover it `{{ $ := . }}`. + `$` also denotes the beginning of a variable, which maybe be initialized inside a template action. So data passed around template pipeline can be initialized using syntax > `$variable := value`. Previously declared variable can also be assigned with new data > `$variable = value`, it has to have a white-space before it or control panel will error out. Variable scope extends to the `end` action of the control structure (`if`, `with`, `range`, `etc.`) in which it is -declared, or to the end of custom command if there are no control structures - call it global scope. +declared, or to the end of custom command if there are no control structures - call it global scope. ## Pipes @@ -97,7 +73,7 @@ would be `{{ add 2 (randInt 41) }}`. Same pipeline but using a variable is also not return anything as printout, 40 still goes through pipeline to addition and 42 is stored to variable `$x` whereas `{{($x:=40)| add 2}}` would return 42 and store 40 to `$x`. -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Use Sparingly" icon="outline/alert-octagon" >}} Pipes are useful in select cases to shorten code and in some cases improve readability, but they **should not be overused**. In most cases, pipes are unnecessary and cause a dip in readability that helps nobody. @@ -108,7 +84,7 @@ overused**. In most cases, pipes are unnecessary and cause a dip in readability Context data refers to information accessible via the dot, `{{ . }}`. The accessible data ranges from useful constants to information regarding the environment in which the custom command was executed, such as the user that ran it, the -channel it was ran in, and so on. +channel it was ran in, and so on. Fields documented as accessible on specific structures, like the context user `.User`, are usable on all values that share the same type. That is, given a user `$user`, `$user.ID` is a valid construction that yields the ID of the user. @@ -196,13 +172,9 @@ Similarly, provided a channel `$channel`, `$channel.Name` gives the name of the ### Interaction -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} - Use of interactions within YAGPDB is an advanced topic; the documentation should be used only as reference. To learn about using interactions, please view our [interactions cookbook](/docs/reference/custom-interactions). -{{< /callout >}} - This is available and part of the dot when a component or modal trigger is used. | **Field** | **Description** | @@ -350,15 +322,15 @@ Branching using `if` action's pipeline and comparison operators - these operator `if` statements always need to have an enclosing `end`.\ Learning resources covers conditional branching [more in depth](https://learn.yagpdb.xyz/beginner/control_flow_1).\ -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Test Many Arguments at Once" icon="outline/rocket" >}} -`eq` , though often used with 2 arguments (`eq x y`) can actually be used with more than 2. If there are more than 2 +`eq`, though often used with 2 arguments (`eq x y`) can actually be used with more than 2. If there are more than 2 arguments, it checks whether the first argument is equal to any one of the following arguments. This behavior is unique to `eq`. {{< /callout >}} -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Only Compare the Same Data Type" icon="outline/info-circle" >}} Comparison operators always require the same type: i.e comparing `1.23` and `1` would throw **`incompatible types for comparison`** error as they are not the same type (one is float, the other int). To fix this, you should convert both to @@ -397,7 +369,7 @@ the same type -> for example, `toFloat 1`. channels. The dot `.` is set to successive elements of those data structures and output will follow execution. If the value of pipeline has zero length, nothing is output or if an `{{else}}` action is used, that section will be executed. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Continue and Break a Loop" icon="outline/info-circle" >}} To skip execution of a single iteration and jump to the next iteration, the `{{continue}}` action may be used. Likewise, if one wishes to skip all remaining iterations, the `{{break}}` action may be used. These both are usable also inside @@ -432,27 +404,37 @@ Like `if`, `range`is concluded with`{{end}}`action and declared variable scope i {{ $x := 42 }} {{ range $x := seq 2 4 }} {{ $x }} {{ end }} {{ $x }} ``` -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Stripping Whitespace Characters" icon="outline/alert-octagon" >}} -**Custom command response was longer than 2k (contact an admin on the server...)**\ -or \ -**Failed executing template: response grew too big (>25k)** +If you're getting an error along the lines of `Custom command response was longer than 2k` or `response grew too big +(>25k)`, that means you're rendering a lot of whitespace characters. -\ -This is quite common error users will get whilst using range. Simple example to reproduce it:\ -_\{{ range seq 0 10000 \}}_\ -_\{{ $x := . \}}_\ -_\{{ end \}}_\ -_HELLO!_\ -This will happen because of whitespaces and newlines, so make sure you one-line the range or trim spaces, in this -context _\{{- $x := . -\}}_ +Consider the following code: + +```yag +{{ range 10000 }} + {{ $x := . }} +{{ end }} +Hello! +``` +This program iterates ten *thousand* times, adding a newline and a tab character on every iteration to the output---we +can fix this error by telling the bot to throw away (or "strip") whitespace characters by using the trim indicator `-`: + +```yag +{{ range 10000 }} + {{- $x := . -}} +{{ end }} +Hello! +``` + +This code will work as expected: iterating 10000 times essentially doing nothing, then sending `Hello!` to the chat. {{< /callout >}} ### Try-catch Multiple template functions have the possibility of returning an error upon failure. For example, `dbSet` can return a -short write error if the size of the database entry exceeds some threshold. +short write error if the size of the database entry exceeds some threshold. While it is possible to write code that simply ignores the possibility of such issues occurring (letting the error stop the code completely), there are times at which one may wish to write more robust code that handles such errors @@ -563,7 +545,7 @@ To define an associated template, use the `define` action. It has the following {{ end }} ``` -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Associated Templates at Top Level" icon="outline/alert-octagon" >}} **Warning:** Template definitions must be at the top level of the custom command program; in other words, they cannot be nested in other actions (for example, an if action.) That is, the following custom command is invalid: @@ -590,7 +572,7 @@ template; that is, the following custom command is invalid, as the body of the a ``` If accessing the value of `$name` is desired, then it needs to be passed as part of the context when executing the -associated template. +associated template. Within the body of an associated template, the variable `$` and the context dot (`.`) both initially refer to the data passed as context during execution. Consequently, any data on the original context that needs to be accessed must be @@ -607,10 +589,10 @@ an associated template that always returns `1`: Note that it is not necessary for a value to be returned; `{{ return }}` by itself is completely valid. -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Clean up Your Code With `return`" icon="outline/rocket" >}} -**Note:** Since all custom commands are themselves templates, using a `return` action at the top level is perfectly -valid, and will result in execution of the custom command being stopped at the point the `return` is encountered. +Since all custom commands are themselves templates, using a `return` action at the top level is perfectly valid, and +will result in execution of the custom command being stopped at the point the `return` is encountered. ```yag {{ if not .CmdArgs }} @@ -633,7 +615,7 @@ To execute a custom command, one of three methods may be used: `template`, `bloc value. Note that the name of the template to execute must be a string constant; similar to `define` actions, a variable referencing a value of string type is invalid. Data to use as the context may optionally be provided following the name. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Consider Using `execTemplate`" icon="outline/info-circle" >}} While `template` is function-like, it is not an actual function, leading to certain quirks; notably, it must be used alone, not part of another action (like a variable declaration), and the data argument need not be parenthesized. Due to @@ -698,22 +680,22 @@ template and may be used as part of another action. Below is an example using `e ## Custom Types Go has built-in primitive data types (_int_, _string_, _bool_, _float64_, ...) and built-in composite data types -(_array_, _slice_, _map_, ...) which also are used in custom commands. \ -\ +(_array_, _slice_, _map_, ...) which also are used in custom commands. + YAGPDB's templating "engine" has currently two user-defined, custom data types - _templates.Slice_ and _templates.SDict_. There are other custom data types used like _discordgo.Timestamp_, but these are outside of the main -code of YAGPDB, so not explained here further. Type _time.Time_ is covered in its own [section](#time).\ -\ +code of YAGPDB, so not explained here further. Type _time.Time_ is covered in its own [section](#time). + Custom Types section discusses functions that initialize values carrying those _templates.Slice_ (abridged to _cslice_), _templates.SDict_ (abridged to _sdict_) types and their methods. Both types handle type _interface{}_ element. It's called an empty interface which allows a value to be of any type. So any argument of any type given is handled. (In "custom commands"-wise mainly primitive data types, but _slices_ as well.) -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Reference Type-Like Behavior" icon="outline/alert-octagon" >}} -**Reference type-like behavior:** Slices and dictionaries in CCs exhibit reference-type like behavior, which may be -undesirable in certain situations. That is, if you have a variable `$x` that holds a slice/dictionary, writing `$y := -$x` and then mutating `$y` via `Append`/`Set`/`Del`/etc. will modify `$x` as well. For example: +Slices and dictionaries in CCs exhibit reference-type like behavior, which may be undesirable in certain situations. +That is, if you have a variable `$x` that holds a slice/dictionary, writing `$y := $x` and then mutating `$y` via +`Append`/`Set`/`Del`/etc. will modify `$x` as well. For example: ```yag {{ $x := sdict "k" "v" }} @@ -724,7 +706,7 @@ $x` and then mutating `$y` via `Append`/`Set`/`Del`/etc. will modify `$x` as wel that is, modifying $y changed $x too. */}} ``` -If this behavior is undesirable, copy the slice/dictionary via `cslice.AppendSlice` or a `range` + `Set` call . +If this behavior is undesirable, copy the slice/dictionary via `cslice.AppendSlice` or a `range` + `Set` call. ```yag {{ $x := sdict "k" "v" }} @@ -741,7 +723,7 @@ aforementioned operation recursively. ### templates.Slice -`templates.Slice` - This is a custom composite data type defined using an underlying data type _\[]interface{}_ . It is +`templates.Slice` - This is a custom composite data type defined using an underlying data type _\[]interface{}_. It is of kind _slice_ (similar to _array_) having _interface{}_ type as its value and can be initialized using `cslice` function. Retrieving specific element inside _templates.Slice_ is by indexing its position number. @@ -807,26 +789,26 @@ Adding "color3" as "blue": {{ $x.Set "color3" "blue" }} **{{ $x }}** Deleting key "color1" {{ $x.Del "color1" }} and whole sdict: **{{ $x }}** ``` -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Database Serialization" icon="outline/rocket" >}} -**Tip:** Previously, when saving cslices, sdicts, and dicts into database, they were serialized into their underlying -native types - slices and maps. This meant that if you wanted to get the custom type back, you needed to convert -manually, e.g. `{{cslice.AppendSlice $dbSlice}}` or `{{sdict $dbDict}}`. Recent changes to YAG have changed this: values -with custom types are now serialized properly, making manual conversion unnecessary. +Previously, when saving cslices, sdicts, and dicts into database, they were serialized into their underlying native +types - slices and maps. This meant that if you wanted to get the custom type back, you needed to convert manually, e.g. +`{{cslice.AppendSlice $dbSlice}}` or `{{sdict $dbDict}}`. Recent changes to YAG have changed this: values with custom +types are now serialized properly, making manual conversion unnecessary. {{< /callout >}} ## Database You have access to a basic set of Database functions having return of type _\*customcommands.LightDBEntry_ called here -[DBEntry](#dbentry). \ +[DBEntry](#dbentry). This is almost a key value store ordered by the key and value combined. You can have max 50 \* user_count (or 500 \* user_count for premium) values in the database, if you go above this all -new write functions will fail, this value is also cached so it won't be detected immediately when you go above nor +new write functions will fail, this value is also cached, so it won't be detected immediately when you go above nor immediately when you're under again. -Patterns are basic PostgreSQL patterns, not Regexp: An underscore `(_)` matches any single character; a percent sign +Patterns are basic PostgreSQL patterns, not RegEx: An underscore `(_)` matches any single character; a percent sign `(%)` matches any sequence of zero or more characters. Keys can be max 256 bytes long and has to be strings or numbers. Values can be anything, but if their serialized @@ -860,16 +842,7 @@ Learning resources covers database [more in-depth](https://learn.yagpdb.xyz/inte ## Tickets -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} - -Ticket functions are limited to 1 call per custom command for both normal and premium guilds and limited to max 10 open -tickets per user. - -{{< /callout >}} - -| **Function** | **Description** | -| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `createTicket author topic` | Creates a new ticket with the author and topic provided. Author can be `nil` (to use the triggering member); user ID in form of a string or an integer; a user struct; or a member struct. The topic must be a string. Returns a [template ticket](#template-ticket) struct on success. | +See [`createTicket`](functions#createTicket) for creating a ticket. ### Template Ticket diff --git a/content/docs/tools-and-utilities/autorole.md b/content/docs/tools-and-utilities/autorole.md index 49080d0..da67f63 100644 --- a/content/docs/tools-and-utilities/autorole.md +++ b/content/docs/tools-and-utilities/autorole.md @@ -5,18 +5,17 @@ description = "Automatically assign roles to members when they join." +++ -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Required Permissions" icon="outline/info-circle" >}} Make sure that the bot has permission to manage roles **and** that the role the bot is assigning is below the highest role the bot has. {{< /callout >}} -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Discord Verification Levels" icon="outline/alert-triangle" >}} -**Warning:** Be careful when using autorole to automatically give new members roles. Discord's in-built new member -verification only works on members with no roles, rendering it useless if members are given roles right after they -join. +Be careful when using autorole to automatically give new members roles. Discord's in-built new member verification only +works on members with no roles, rendering it useless if members are given roles right after they join. {{< /callout >}} diff --git a/content/docs/tools-and-utilities/self-assignable-roles.md b/content/docs/tools-and-utilities/self-assignable-roles.md index 8056148..18ad75d 100644 --- a/content/docs/tools-and-utilities/self-assignable-roles.md +++ b/content/docs/tools-and-utilities/self-assignable-roles.md @@ -14,15 +14,17 @@ description = "how2 reaction role" ## Roles -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Required Bot Permissions" icon="outline/alert-triangle" >}} -Make sure that the bot has the _manage role_ permission and that the bot's role is **above** the role it is trying to assign. +Make sure that the bot has the _manage role_ permission and that the bot's role is **above** the role it is trying to +assign. {{< /callout >}} -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Required User Permissions" icon="outline/alert-triangle" >}} -If you want to use any of the `rolemenu` commands, you **need** to have the `MANAGE_GUILD` permission, or the Manage Server permission. This is hardcoded, meaning that command overrides will not affect it. +If you want to use any of the `rolemenu` commands, you **need** to have the `MANAGE_GUILD` permission, or the +Manage Server permission. This is hard-coded, meaning that command overrides will not affect it. {{< /callout >}} @@ -30,11 +32,12 @@ Simply give the role command a name and then select which role you want the bot ![Creation of a role command](role_command_creation.png) -### Optional features +### Optional features{#roles-optional-features} -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Required and Ignored Roles" icon="outline/alert-triangle" >}} -Do **not** set the require role to the role you are assigning. You generally will not want to set the ignore role to the role you are assigning either _unless_ you wish to prevent the user from removing that role through the role-menu. +Do **not** set the required role to the role you are assigning. You generally will not want to set the ignore role to +the role you are assigning either, _unless_ you wish to prevent the user from removing that role through the role-menu. {{< /callout >}} @@ -44,15 +47,18 @@ Do **not** set the require role to the role you are assigning. You generally wil ## Role Groups -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Role Menu Configuration" icon="outline/info-circle" >}} Role groups are essential if you want to set up a role menu. {{< /callout >}} -Role groups are useful for applying restrictions on a group of roles such as only being able to have one or the other role etc. They're also essential if you want to create a role menu. To create one, simply give the role group a name and then select which mode you want the role group to use. +Role groups are useful for applying restrictions on a group of roles such as only being able to have one or the other +role etc. They're also essential if you want to create a role menu. To create one, simply give the role group a name and +then select which mode you want the role group to use. -Every role group, even Ungrouped has the option to delete all roles inside that group, other groups will not be affected. Be careful with that, it's permanent and can't be undone. +Every role group, even Ungrouped has the option to delete all roles inside that group, other groups will not be +affected. Be careful with that, it's permanent and can't be undone. ![Creation of a role command group](role_command_group_creation.png) @@ -62,11 +68,12 @@ Every role group, even Ungrouped has the option to delete all roles inside that 2. Single: They can only have 1 role in the group. (e.g. for colors) 3. Multiple: You can set the minimum and maximum number of roles a member can have in the group. -### Optional features +### Optional features{#groups-optional-features} -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Required and Ignored Roles" icon="outline/alert-triangle" >}} -Do **not** set the require role to the role you are assigning. You generally will not want to set the ignore role to the role you are assigning either _unless_ you wish to prevent the user from removing that role through the rolemenu. +Do **not** set the required role to the role you are assigning. You generally will not want to set the ignore role to +the role you are assigning either, _unless_ you wish to prevent the user from removing that role through the rolemenu. {{< /callout >}} @@ -81,7 +88,8 @@ Role groups have additional options that can be enabled/disabled by selecting th #### Example usage: -Say you have a server with 3 factions and want people to be able to assign their own faction when they join. That's simple enough - all we have to do is: +Say you have a server with 3 factions and want people to be able to assign their own faction when they join. That's +simple enough - all we have to do is: - Create the 3 roles - Create 3 role commands for those roles @@ -91,23 +99,28 @@ Now everyone can assign themselves a faction! There are a couple of issues with 1. You can assign yourself more than 1 faction. 2. People can freely jump between factions. -To fix these problems we can create a new group with the mode `Single` and assign the previous role commands to that group. Great! Now we can only have 1 faction! How can we solve jumping between factions then? You can enable the `Require 1 role in group` setting, now they can't remove roles in the group, and they can have max. 1 role in the group, so they can't jump around anymore! +To fix these problems we can create a new group with the mode `Single` and assign the previous role commands to that +group. Great! Now we can only have 1 faction! How can we solve jumping between factions then? You can enable the +`Require 1 role in group` setting, now they can't remove roles in the group, and they can have max. 1 role in the group, +so they can't jump around anymore! ### Adding roles to the role group -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: One Group Only" icon="outline/info-circle" >}} Roles can only be assigned to one group. {{< /callout >}} -Refer back to the [optional features](#optional-features) for roles and select the role group you want to assign the role to. +Refer back to the [optional features for roles](#roles-optional-features) and select the role group you want to assign +the role to. ## Role Menu -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Required Setup" icon="outline/alert-triangle" >}} -Make sure you created your [role commands](#roles) and assigned them a [role group](#role-groups) before starting. Role menu will **not** work if you have not done so. +Make sure you created your [role commands](#roles) and assigned them a [role group](#role-groups) before starting. +Role menu will **not** work if you have not done so. {{< /callout >}} @@ -115,15 +128,18 @@ The role menu makes it possible to have people assign roles by adding reactions ![Example of a role menu](rolemenu_example.png) -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Custom Embeds" icon="outline/info-circle" >}} -If you'd like to create a message like the above to create a rolemenu on, take a look at the [Custom Embeds](/docs/reference/custom-embeds) chapter. +If you'd like to create a message like the above to create a rolemenu on, take a look at the +[Custom Embeds](/docs/reference/custom-embeds) chapter. {{< /callout >}} -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Message Reactions Limit" icon="outline/alert-triangle" >}} -A role menu can only support up to 20 roles due to the reaction limit discord places on messages. If your role group has more then twenty you have to use finish sub-command and then add the rest of roles to a new message with -skip flag. +A role menu can only support up to 20 roles due to the reaction limit discord places on messages. +If your role group has more then twenty you have to use finish sub-command and then add the rest of roles to a new +message with -skip flag. {{< /callout >}} @@ -131,13 +147,16 @@ To set up a role menu, the related roles **have to be added to a role group**, t The group mode and other restrictions from the role group and role still apply to the roles in the role menu. -After you type in the command, you will be taken through the setup process. If you want to disable DMs, create a custom message, or add new role to your role menu, be sure to read until the end. +After you type in the command, you will be taken through the setup process. If you want to disable DMs, create a custom +message, or add new role to your role menu, be sure to read until the end. ### Step by step tutorial -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Prerequisites" icon="outline/alert-triangle" >}} -Make sure you created your [role commands](#roles) and assigned them a [role group](#role-groups) before starting. Role menu will **not** work if you have not done so. All switches and flags (nodm, rr, etc...) start with hyphen symbol `-`, not your prefix. +Make sure you created your [role commands](#roles) and assigned them a [role group](#role-groups) before starting. +Role menu will **not** work if you have not done so. All switches and flags (nodm, rr, etc...) start with hyphen symbol +`-`, not your prefix. {{< /callout >}} @@ -147,7 +166,8 @@ to send `-rolemenu create Sports`. ![Rolemenu Create command](rolemenu_create.png) -As you can see, the bot started creating the menu, and has asked you to add the emoji for the first role, **Soccer**. I'll react on the message with my emoji of choice: +As you can see, the bot started creating the menu, and has asked you to add the emoji for the first role, **Soccer**. +I'll react on the message with my emoji of choice: ![First reaction on a rolemenu setup](rolemenu_react.png) @@ -159,29 +179,37 @@ And similar for the final role, **Basketball:** ![Third reaction on a rolemenu setup](rolemenu_react_3.png) -And we're done --- people can start using the menu by clicking on the reaction associated with their desired role. The setup message will be automatically deleted in a couple of minutes, but you can also delete it manually, if you so desire. +And we're done --- people can start using the menu by clicking on the reaction associated with their desired role. +The setup message will be automatically deleted in a couple of minutes, but you can also delete it manually, if you so +desire. ### Custom message -To create a custom message for your role menu like event role menu you saw above, you will need to send a message. Then get the ID of the message by following the steps in [how to get a message ID](#how-to-get-a-message-id-desktop) and type in the following command, `-rolemenu create (group name) -m (message id)`. You would then complete the role menu like you would any normal role menu. +To create a custom message for your role menu like event role menu you saw above, you will need to send a message. +Then get the ID of the message by following the steps in [how to get a message ID](#how-to-get-a-message-id-desktop) and +type in the following command, `-rolemenu create (group name) -m (message id)`. You would then complete the role menu +like you would any normal role menu. ### Disabling DM confirmation -If you do not want the bot to send you a DM when you are given or removed from a role, type in the following command `-rolemenu update (message id) -nodm`. +If you do not want the bot to send you a DM when you are given or removed from a role, type in the following command +`-rolemenu update (message id) -nodm`. After you have finish editing or creating your role menu, it will display whether DM notifications are enabled or not. ![Rolemenu flags display](rolemenu_flags.png) -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Errors Cannot be Disabled" icon="outline/alert-triangle" >}} -Note that YAGPDB does not allow you to disable warning DMs such as cool-down messages with the `nodm` switch or any other method. +Note that YAGPDB does not allow you to disable error messages such as cool-down messages with the `nodm` switch or any +other method. {{< /callout >}} ### Remove roles on reaction remove -Remove roles on reaction remove, this means instead of the old toggling mode, adding reactions will strictly give you the role, and removing reactions will only take away the role from you. This mode is on by default for new menus. +Remove roles on reaction remove, this means instead of the old toggling mode, adding reactions will strictly give you +the role, and removing reactions will only take away the role from you. This mode is on by default for new menus. You can set old menus to use this switch using the command `rolemenu update (message id) -rr`. @@ -189,28 +217,38 @@ You can set old menus to use this switch using the command `rolemenu update (mes ### Removing a role menu -If you want to remove a role menu from a message, you can type in `-rolemenu remove (message id)` It will remove the role-menu from a message. The message itself won't be deleted but the bot will now not do anything with reactions on that message. +If you want to remove a role menu from a message, you can type in `-rolemenu remove (message id)` It will remove the +role-menu from a message. The message itself won't be deleted but the bot will now not do anything with reactions on +that message. ### Editing a role menu -If you want to change the emote for one your reaction, you can do so by typing in `-rolemenu edit (message id)` After you type it the command it will ask you to react on the emote you want to change. You will need to go to the role menu and react on the emote you want to change. After you have reacted on the desired emote, it will ask you to react with your new emote on the role menu. +If you want to change the emote for one your reaction, you can do so by typing in `-rolemenu edit (message id)` After +you type it the command it will ask you to react on the emote you want to change. You will need to go to the role menu +and react on the emote you want to change. After you have reacted on the desired emote, it will ask you to react with +your new emote on the role menu. ### Resetting all reactions -If you edit your reaction emotes or simply want to give your emote a new clean slate. You can reset all the reactions by typing in `-rolemenu resetreactions (message id)`. It will remove all reactions on this menu and re-adds them, can be used to fix the order. +If you edit your reaction emotes or simply want to give your emote a new clean slate. You can reset all the reactions +by typing in `-rolemenu resetreactions (message id)`. It will remove all reactions on this menu and re-adds them, can +be used to fix the order. ### Updating a role menu -If you added a new role to your role group, you can update your role menu. Update it by typing in `-rolemenu update (message id)` and follow the instructions given. If you removed a role, you will have to delete it and make a new one from scratch. +If you added a new role to your role group, you can update your role menu. Update it by typing in +`-rolemenu update (message id)` and follow the instructions given. If you removed a role, you will have to delete it +and make a new one from scratch. ## How to get a message ID (Desktop) -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Developer Mode" icon="outline/info-circle" >}} Make sure you have [developer mode turned on in your discord settings.](https://support.discordapp.com/hc/en-us/articles/206346498) {{< /callout >}} -To get the ID of the message you want to set the custom role menu on, click on the three dots on the far right hand side of the message and click on `Copy ID.` +To get the ID of the message you want to set the custom role menu on, click on the three dots on the far right hand side +of the message and click on `Copy ID.` ![Copying a message ID](copy_message_id.png) diff --git a/content/docs/tools-and-utilities/tickets.md b/content/docs/tools-and-utilities/tickets.md index 02a8e2e..50cc3df 100644 --- a/content/docs/tools-and-utilities/tickets.md +++ b/content/docs/tools-and-utilities/tickets.md @@ -8,7 +8,7 @@ Tickets let your members interact with your server staff in a private and more o dedicated channel that can only be seen by the staff and the member who created the ticket, with the option to add more users as-needed. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Required Bot Permissions" icon="outline/info-circle" >}} Make sure that the bot has permission to manage channels in the category you want the bot to create tickets in, as well as permission to send messages in said category, the transcript channels, and the ticket log channel. @@ -57,7 +57,7 @@ have different responsibilities, but nothing prevents you from selecting the sam The bot uses channels for tickets, and these channels are created in a category of your choosing. This category should be set up with the necessary permissions for the bot to create channels in it. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Discord Channel Limit" icon="outline/info-circle" >}} Discord limits categories to contain at most 50 channels. If you experience a high volume of tickets, consider closing some or researching alternative bots that handle tickets differently. diff --git a/content/docs/welcome/getting-started.md b/content/docs/welcome/getting-started.md index d6bfd85..f99c466 100644 --- a/content/docs/welcome/getting-started.md +++ b/content/docs/welcome/getting-started.md @@ -8,7 +8,7 @@ description = "The first steps to setting up YAGPDB on your server." ## Adding The Bot -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Required User Permission" icon="outline/info-circle" >}} You need to have the **Manage Server** permission to add the bot to your server. diff --git a/content/docs/welcome/premium.md b/content/docs/welcome/premium.md index 96b36c8..406d1db 100644 --- a/content/docs/welcome/premium.md +++ b/content/docs/welcome/premium.md @@ -71,7 +71,7 @@ A premium server unlocks the following benefits: - Increase maximum YouTube feeds per guild from 50 to 250 (`GuildMaxFeedsPremium`). -{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Disabled Features" icon="outline/alert-octagon" >}} Some features enhanced or enabled by premium have been disabled on Botlabs' publicly hosted instance, often due to ratelimits with 3rd party APIs YAGPDB relies on. diff --git a/content/learn/beginner/conditional-branching.md b/content/learn/beginner/conditional-branching.md index 61f63c4..a1ba2e7 100644 --- a/content/learn/beginner/conditional-branching.md +++ b/content/learn/beginner/conditional-branching.md @@ -50,7 +50,7 @@ them is true: {{ end }} ``` -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Truthiness" icon="outline/info-circle" >}} The condition of an `if` statement need not be a boolean: in general, an `if` statement will trigger if the condition is _truthy_: that is, not empty or zero. (Conversely, empty and zero values are _falsy_.) @@ -97,7 +97,7 @@ In programming, we can make decisions by comparing values to each other. We can types. The result of a comparison is a _boolean_ value, which is either `true` or `false`. Normally, comparisons are binary operators; however, in custom commands, we use functions to compare values. -{{< callout context="caution" title="Comparing across Types" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Comparing Across Types" icon="outline/alert-triangle" >}} Just like you cannot quite compare apples and oranges, you cannot compare values of different types. For instance, you cannot compare a number to a string. The bot will throw an error if you try to do so, you will have to convert either of @@ -144,7 +144,7 @@ Are you cool? {{ $isCool }} It is considered good practice to define variables in the smallest scope possible. This makes your code easier to read and understand, as you do not have to search through the entire codebase to find where a variable was defined. -{{< callout context="caution" title="Definition and Reassignment" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Definition and Reassignment" icon="outline/alert-triangle" >}} In custom commands, you use `:=` to define a variable, and `=` to reassign a variable. The bot will not throw an error if you try to re-define a variable using `:=`. Rather, it will define a new variable, effectively overwriting the @@ -152,7 +152,7 @@ existing variable, but only within that scope---the existing variable is untouch {{< /callout >}} -{{< callout context="danger" title="Unexpected EOF" icon="outline/alert-octagon" >}} +{{< callout context="danger" title="Danger: Unexpected EOF" icon="outline/alert-octagon" >}} The following error appears when you are missing an `{{ end }}` action. @@ -194,7 +194,7 @@ pattern found in text; the dot "3" contains the match Note that the dot `.` has been set to `"3"`—the result of `reFind`. See if you can change the text stored in `$msg` so that the program hits the `else` branch instead. -{{< callout context="caution" title="Warning" icon="outline/alert-triangle" >}} +{{< callout context="caution" title="Warning: Readability of `with` Blocks" icon="outline/alert-triangle" >}} Be careful not to overuse `with` blocks, as they can make your code difficult to follow. In general, prefer using a normal `if` conditional and only use `with` if it improves readability; do not use it just to shorten code. diff --git a/content/learn/beginner/variables-and-data-types.md b/content/learn/beginner/variables-and-data-types.md index 45a5b33..b9da5d0 100644 --- a/content/learn/beginner/variables-and-data-types.md +++ b/content/learn/beginner/variables-and-data-types.md @@ -26,7 +26,7 @@ illustrate this, consider the following example: Later on, we may wish to reassign a new value to a variable. We can do this by using the re-assignment operator `=`. When and why this becomes necessary will be discussed in a later chapter. -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Troubleshooting Data Types" icon="outline/rocket" >}} When debugging your code, you might have to figure out the type of a certain variable. You can do this by using the [`printf` function](/docs/reference/templates/functions/#string-manipulation) with the `%T` format verb, like so: diff --git a/content/learn/intermediate/database.md b/content/learn/intermediate/database.md index e6a2687..3271d66 100644 --- a/content/learn/intermediate/database.md +++ b/content/learn/intermediate/database.md @@ -32,9 +32,10 @@ A database entry has the following structure: | .Value | The value of this entry. | | .ValueSize | The size of the value in bytes. | -The fields `.CreatedAt`, `.UpdatedAt`, and `.ExpiresAt` all evaluate to a `time.Time` object, so all [methods on `time.Time`](/docs/reference/templates/functions#time) are applicable. +The fields `.CreatedAt`, `.UpdatedAt`, and `.ExpiresAt` all evaluate to a `time.Time` object, so all +[methods on `time.Time`](/docs/reference/templates/functions#time) are applicable. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: About That User ID" icon="outline/info-circle" >}} The user ID does not have to point to a valid Discord user—it can be any integer. For instance, it is conventional (but not required) to store server-global data under the user ID `0`, in which case the `UserID` field will be `0` and the @@ -117,7 +118,7 @@ If no such entry exists, it returns `nil`. {{ dbGet user_id key }} ``` -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Beware the Return Type" icon="outline/info-circle" >}} `dbGet` returns the database entry object, not the value. To access the value, read the `Value` field: @@ -192,7 +193,7 @@ A common use case for this function is a cooldown: As long as the entry exists, Command is not on cooldown :) ``` -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Backend Expiry Behavior" icon="outline/info-circle" >}} As a side effect, expired entries will be considered gone (i.e. deleted) by YAGPDB, but still remain in the underlying database. You can observe this effect by visiting your [database view page](/docs/custom-commands/database). diff --git a/content/learn/intermediate/embeds-and-messages.md b/content/learn/intermediate/embeds-and-messages.md index bd8a043..5a259c1 100644 --- a/content/learn/intermediate/embeds-and-messages.md +++ b/content/learn/intermediate/embeds-and-messages.md @@ -104,7 +104,7 @@ field. This field is a boolean that determines whether the field should be displ The `"author"` field is a dictionary that contains the name and icon URL of the author of the embed. In this case, we use the username of the user who triggered the custom command as the name, and the user's avatar URL as the icon URL. -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Custom Commands Embed Generator" icon="outline/rocket" >}} There is a [community-made embed visualizer][v-embed] that can help you create custom command embeds more easily. However, it is still a good idea to not wholly rely on the GUI and understand the structure of the embeds yourself. @@ -182,7 +182,7 @@ the title and description of the embed, and remove all fields. Finally, we send As mentioned previously, this example is contrived: in practice, we're more likely to use `.Message.Embeds` to get the original embed object, convert and modify it as shown above, then send it back to the `editMessage` function. -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Full Conversion" icon="outline/info-circle" >}} `structToSdict` does not perform deep conversion. For a full conversion of an embed to a dictionary, you can use the following code snippet: diff --git a/content/learn/intermediate/loops.md b/content/learn/intermediate/loops.md index 6b1b082..dc72e78 100644 --- a/content/learn/intermediate/loops.md +++ b/content/learn/intermediate/loops.md @@ -133,9 +133,9 @@ program is erroneous: {{ end }} ``` -{{< callout context="note" title="Note" icon="outline/info-circle" >}} +{{< callout context="note" title="Note: Index-Value-Pairs of a Slice" icon="outline/info-circle" >}} -The two-variable form of range can also be used with a slice, in which case the first variable tracks the position of +This two-variable form of `range` can also be used with a slice, in which case the first variable tracks the position of the element starting from `0`. {{< /callout >}} @@ -250,7 +250,7 @@ For instance, the following code loops as long as `$n` is not 1. In each iterati As with `range`, it is also possible to attach a `else` branch to a `while` loop, executed if the condition is falsy initially. -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Idiomatic Iteration" icon="outline/rocket" >}} Many `while` loops can be written as a more idiomatic range loop instead. In particular, to iterate a fixed number of times, use `{{ range n }}` as in `{{ range 5 }}` instead of maintaining your own counter variable with `while`. diff --git a/content/learn/intermediate/maps-and-slices.md b/content/learn/intermediate/maps-and-slices.md index bb8881a..ac5c1a2 100644 --- a/content/learn/intermediate/maps-and-slices.md +++ b/content/learn/intermediate/maps-and-slices.md @@ -27,7 +27,7 @@ For available operations on slices, please refer to [our template documentation] [docs-slices]: /docs/reference/templates/syntax-and-data/#templatesslice -{{< callout context="tip" title="Tip" icon="outline/rocket" >}} +{{< callout context="tip" title="Tip: Truthiness of Empty Slices" icon="outline/rocket" >}} Empty slices are _falsy_, so can be used directly in conditional statements; it is not necessary to explicitly check the length: @@ -78,7 +78,7 @@ For available operations on maps, please refer to [our template documentation][d [docs-maps]: /docs/reference/templates/syntax-and-data/#templates-sdict -{{< callout context="tip" title="Here be Dragons" icon="outline/rocket" >}} +{{< callout context="note" title="Note: Maps Print Ordered by Key" icon="outline/info-circle" >}} Consider the following code that displays the value of `$fruitPrices` as defined in the previous example: