skriptlang / skript-docs

Documentation Site for Skript Plugin

---

Skript Documentation Site

Skript's features are documented directly in it's Java code. But we still need

1. Clear tutorials, not just "you can check the syntax pattern"
2. Examples explained, if needed
3. Addon tutorials
4. Syntax patterns explained

Folders Structure

• docs/templates/ is used by Skript Docs generation process to produce the docs pages (docs/).
• docs/ is the production files where Github pages displays the content of.
• docs/nightly/master/ is Skript's nightly builds documentation pages (this gets updated with every commit to master/dev branches in Skript's repo).

You can find more about the docs templates in docs/templates.

Generating the documentation

Currently, the docs files is generated using Skript plugin.

1. You will need to create a directory named docs/templates in plugins/Skript/, and copy everything from docs/templates folder into that directory.
2. Execute the command /sk gen-docs.
3. The docs/ directory will be created (if not created already) in plugins/Skript containing the website's files.
4. Open index.html and browse the documentation.
5. (Optionally) Add this system property -Dskript.forceregisterhooks in your server startup script (before the -jar property) to force generating hooks docs.

skript-docs's Issues

store negative cookie preference

when an user rejects cookies, we should keep their preference in localStorage so that they aren't asked again

probably add some stuff here:

skript-docs/doc-templates/js/main.js

Lines 404 to 406 in fd47b5e

	cookiesDeny.addEventListener('click', () => {
	cookiesBar.remove();
	});

and here:

skript-docs/docs/archives/2.6.4/js/functions.js

Line 1 in fd47b5e

let isCookiesAccepted = getCookie("cookies-accepted") === "true";

and here as well:

skript-docs/doc-templates/js/main.js

Line 392 in fd47b5e

if (!isCookiesAccepted) {

:)

Website Homepage

Description

I suggest adding a redirection from http://skriptlang.github.io/ to http://skriptlang.github.io/Skript, as currently, http://skriptlang.github.io/ leads to a "404" error, and only http://skriptlang.github.io/Skript works. It would be really useful ^^

🐛 docs.json bugs

1- Patterns include hyper links

2- Some examples (like events) use \\n instead of an actual new json element

3- What is pattern_end?

4- Quotes are not escaped

5- What is end=true

6- Some new lines aren't replaced correctly

Add copy to clipboard text.html documentation

Add documentation for copy clipboard from pull request SkriptLang/Skript#5353 to text.html

Deprecation Annotation | Skript Syntaxes

Is this exclusive to just skript methods or would be it also be something good for skript syntax aswell?

An example case for this would be if there was ever a PR for raytrace syntax, for the most part that is just a better target block and target entity as it acts more like an exact target entity. In that case I'd view it as a means for a deprecation/removal of the target syntaxes *could also just be time for an update to raytrace

Originally posted by @Fusezion in SkriptLang/Skript#5278 (comment)

---

Suggestion

As I stated above, I believe there should also be a new annotation in skript just like the @MarkedForRemoval but this time aimed for general skript syntax such as @Deprecation

Why

In the example above I mentioned we could theoretically remove the target block and target entity expressions if we were to ever add support for raytracing in skript. That's due to the fact raytracing is a just much exact hit compared to target attempting to get "around" it as it treats all blocks as full blocks

Adding this does another thing which is prevent removal of largely used syntax feeling like it randomly happened we'd be able to now mark stuff as Deprecated early on after introducing something to replace it and wait a few(1-2) major versions then remove it.

Detail all configuration nodes and hidden nodes for the config.sk

Detail all configuration nodes and hidden nodes for the config.sk

There are hidden nodes, and there really is no point in having them hidden when they're not documented anywhere. They're hidden because they're a "only change if you know what you're doing" type of node.

💡 Specify actual return types of Object expressions

Expressions such as ExprAllBannedEntries have a return type of Object, but getReturnType method returns actual return types based on condition, we should find a way to return all values regardless of conditions

🐛 Keywords not handled for classes and functions

[BUG] the isNew system doesn't account for additions to Since tag

In 2.7 skript updated ExprSets (named "Sets") to include enum classinfos, when you click on isNew button to limit it to all 2.7 syntax "Sets" doesn't appear as shown in the image, this is likely caused by doing an exact search for @Since("2.7") and not checking if it contains it.

Calling this a bug as I don't believe this was intended behavior and just went unnoticed.

Add copy syntax button

Add a button to allow for copying of the syntax text

Add tablist search option to playerlist header footer

https://docs.skriptlang.org/expressions.html?search=#ExprPlayerlistHeaderFooter this is missing a very important search option, tablist (pointed out by fusezion), the reason I say this is because this is also considered a tablist, so it would make sense if you lookup tablist on the docs and this would appear.

Missing values for firework effect

https://docs.skriptlang.org/classes.html#fireworkeffect

Missing the types of the firework effects for the launch effect.

🐛 Repetitive HTML characters escaping

Original example: "message \"You're holding a <%color of tool%>%color of tool%<reset> wool block\"

Result

🐛 Expressions returning Java classes missing return type

🐛 Missing lang enum constant for 'damage causes.WORLD_BORDER' / 'damage causes.KILL'

13:03:49 ERROR: #!#! [Skript] Severe Error:
13:03:49 ERROR: #!#!
13:03:49 ERROR: #!#! Something went horribly wrong with Skript.
13:03:49 ERROR: #!#! This issue is NOT your fault! You probably can't fix it yourself, either.
13:03:49 ERROR: #!#! It looks like you are using some plugin(s) that alter how Skript works (addons).
13:03:49 ERROR: #!#! Here is full list of them:
13:03:49 ERROR: #!#! skript-reflect v2.3.1-for-skript-beta (https://github.com/TPGamesNL/skript-reflect) SkBee v2.13.0 (https://github.com/ShaneBeee/SkBee)
13:03:49 ERROR: #!#! We could not identify which of those are specially related, so this might also be Skript issue.
13:03:49 ERROR: #!#! You should try disabling those plugins one by one, trying to find which one causes it.
13:03:49 ERROR: #!#! If the error doesn't disappear even after disabling all listed plugins, it is probably Skript issue.
13:03:49 ERROR: #!#! In that case, you will be given instruction on how should you report it.
13:03:49 ERROR: #!#! On the other hand, if the error disappears when disabling some plugin, report it to author of that plugin.
13:03:49 ERROR: #!#! Only if the author tells you to do so, report it to Skript's issue tracker.
13:03:49 ERROR: #!#!
13:03:49 ERROR: #!#! Stack trace:
13:03:49 ERROR: #!#! java.lang.NullPointerException: Cannot invoke "String.toCharArray()" because "msg" is null
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.util.chat.ChatMessages.fromParsedString(ChatMessages.java:424)
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.lang.VariableString.getMessageComponents(VariableString.java:453)
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.effects.EffMessage.execute(EffMessage.java:120)
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.lang.Effect.run(Effect.java:50)
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.lang.TriggerItem.walk(TriggerItem.java:62)
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.lang.TriggerItem.walk(TriggerItem.java:90)
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.lang.Trigger.execute(Trigger.java:52)
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.SkriptEventHandler.check(SkriptEventHandler.java:146)
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.SkriptEventHandler.access$000(SkriptEventHandler.java:50)
13:03:49 ERROR: #!#! at Skript-2.7.0-beta3.jar//ch.njol.skript.SkriptEventHandler$PriorityListener.lambda$new$0(SkriptEventHandler.java:63)
13:03:49 ERROR: #!#! at co.aikar.timings.TimedEventExecutor.execute(TimedEventExecutor.java:81)
13:03:49 ERROR: #!#! at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:70)
13:03:49 ERROR: #!#! at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54)
13:03:49 ERROR: #!#! at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:126)
13:03:49 ERROR: #!#! at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:615)
13:03:49 ERROR: #!#! at org.bukkit.craftbukkit.v1_20_R1.event.CraftEventFactory.callPlayerDeathEvent(CraftEventFactory.java:922)
13:03:49 ERROR: #!#! at net.minecraft.server.level.EntityPlayer.a(EntityPlayer.java:958)
13:03:49 ERROR: #!#! at net.minecraft.world.entity.EntityLiving.a(EntityLiving.java:1529)
13:03:49 ERROR: #!#! at net.minecraft.world.entity.player.EntityHuman.a(EntityHuman.java:967)
13:03:49 ERROR: #!#! at net.minecraft.server.level.EntityPlayer.a(EntityPlayer.java:1127)
13:03:49 ERROR: #!#! at net.minecraft.world.entity.EntityLiving.ah(EntityLiving.java:321)
13:03:49 ERROR: #!#! at net.minecraft.server.commands.CommandKill.a(CommandKill.java:25)
13:03:49 ERROR: #!#! at net.minecraft.server.commands.CommandKill.b(CommandKill.java:14)
13:03:49 ERROR: #!#! at com.mojang.brigadier.CommandDispatcher.execute(CommandDispatcher.java:265)
13:03:49 ERROR: #!#! at net.minecraft.commands.CommandDispatcher.performCommand(CommandDispatcher.java:324)
13:03:49 ERROR: #!#! at net.minecraft.commands.CommandDispatcher.a(CommandDispatcher.java:308)
13:03:49 ERROR: #!#! at net.minecraft.server.network.PlayerConnection.a(PlayerConnection.java:2299)
13:03:49 ERROR: #!#! at net.minecraft.server.network.PlayerConnection.lambda$handleChatCommand$20(PlayerConnection.java:2259)
13:03:49 ERROR: #!#! at net.minecraft.util.thread.IAsyncTaskHandler.b(IAsyncTaskHandler.java:59)
13:03:49 ERROR: #!#! at java.base/java.util.concurrent.CompletableFuture$AsyncSupply.run(Unknown Source)
13:03:49 ERROR: #!#! at net.minecraft.server.TickTask.run(TickTask.java:18)
13:03:49 ERROR: #!#! at net.minecraft.util.thread.IAsyncTaskHandler.d(IAsyncTaskHandler.java:153)
13:03:49 ERROR: #!#! at net.minecraft.util.thread.IAsyncTaskHandlerReentrant.d(IAsyncTaskHandlerReentrant.java:24)
13:03:49 ERROR: #!#! at net.minecraft.server.MinecraftServer.b(MinecraftServer.java:1339)
13:03:49 ERROR: #!#! at net.minecraft.server.MinecraftServer.d(MinecraftServer.java:197)
13:03:49 ERROR: #!#! at net.minecraft.util.thread.IAsyncTaskHandler.x(IAsyncTaskHandler.java:126)
13:03:49 ERROR: #!#! at net.minecraft.server.MinecraftServer.bg(MinecraftServer.java:1316)
13:03:49 ERROR: #!#! at net.minecraft.server.MinecraftServer.x(MinecraftServer.java:1309)
13:03:49 ERROR: #!#! at net.minecraft.util.thread.IAsyncTaskHandler.c(IAsyncTaskHandler.java:136)
13:03:49 ERROR: #!#! at net.minecraft.server.MinecraftServer.p_(MinecraftServer.java:1287)
13:03:49 ERROR: #!#! at net.minecraft.server.MinecraftServer.w(MinecraftServer.java:1175)
13:03:49 ERROR: #!#! at net.minecraft.server.MinecraftServer.lambda$spin$0(MinecraftServer.java:318)
13:03:49 ERROR: #!#! at java.base/java.lang.Thread.run(Unknown Source)
13:03:49 ERROR: #!#!
13:03:49 ERROR: #!#! Version Information:
13:03:49 ERROR: #!#! Skript: 2.7.0-beta3 (latest)
13:03:49 ERROR: #!#! Flavor: skriptlang-github
13:03:49 ERROR: #!#! Date: 03:18:03.366646700
13:03:49 ERROR: #!#! Bukkit: 1.20.1-R0.1-SNAPSHOT
13:03:49 ERROR: #!#! Minecraft: 1.20.1
13:03:49 ERROR: #!#! Java: 17.0.7 (OpenJDK 64-Bit Server VM 17.0.7+7)
13:03:49 ERROR: #!#! OS: Windows 10 amd64 10.0
13:03:49 ERROR: #!#!
13:03:49 ERROR: #!#! Server platform: Paper
13:03:49 ERROR: #!#!
13:03:49 ERROR: #!#! Current node: null
13:03:49 ERROR: #!#! Current item: send ">> %the damage cause%" to the attacked entity
13:03:49 ERROR: #!#! Current trigger: death (death) (code.sk, line 1)
13:03:49 ERROR: #!#!
13:03:49 ERROR: #!#! Thread: Server thread
13:03:49 ERROR: #!#!
13:03:49 ERROR: #!#! Language: english
13:03:49 ERROR: #!#! Link parse mode: DISABLED
13:03:49 ERROR: #!#!
13:03:49 ERROR: #!#! End of Error.
13:03:49 ERROR: #!#!

on death:
send ">> %damage cause%" to victim

This error occurs when I try to use "damage cause" to either send it as a message or in a condition.

These are the versions I use:

💡 Update Text Tutorial

Bug Description

https://github.com/SkriptLang/Skript/blob/e1c1735ff509250a7a2f8eee9c22100c884eb1d1/src/main/java/ch/njol/skript/classes/data/JavaClasses.java#L554

Out current Text Tutorial page is missing variables, this was the original page but it so old, no longer available features and some content is already written in the current Text Tutorial page.

The last part of our Text tutorial page says A guide about this is coming... some day. that what needs to be updated

Old Variables Tutorial

MORE SUGGESTIONS

• Seperate variables from Text Tutorial and add a new styling box for Related Tutorials (in Text Tut > Variables & in Variables > Text)

Agreement

• I have read the guidelines above and affirm I am following them with this report.

[Suggestion] New aliases in docs

Hello. So I talked to Snow about this today. He informed me that the new Skript for 1.13 does not include the aliases file like previous versions do to not wanting people to mess with them. Totally understandable. For myself, I don't generally change them, I use them more for reference.

So I had two suggestions.

1. Create a command, that a person could run, which would generate an uneditable aliases folder strictly for reference.
   or
2. Add the new aliases to the docs.
   He liked the docs idea and told me to suggest it on here. So there ya go :)

Forgot to update some INSERT VERSION tags for 2.7

Don't really think I need to go into too much detail, 3 classes didn't get updated for INSERT VERSION before updating docs sites.

https://docs.skriptlang.org/docs.html?search=#inventory_drag
https://docs.skriptlang.org/docs.html?search=#EffPotion
https://docs.skriptlang.org/docs.html?search=#CondIsInfinite

💡 Escape HTML tags in examples

I don't think there is any use case for HTML tags in Skript examples

💡 Tutorials Needed

We really need some tutorials in Skript docs. Following topics would be most important:

• if-else blocks explained
• Events handling
• Custom Commands & Command Event
• Sections/Structures Explained
• Loops Explained
• Variables Explained
• Declaring new functions, how returns work
• Chat formatting, especially now with advanced JSON stuff
• Visual effects tutorial, as they can be quite hard no matter how Skript does them

... and probably some more things.

So, anyone interested? Just copying some existing tutorials with authors permission would be good enough. Writing new tutorials wouldn't be bad either, if someone has time for that ;)

Update README about doc-template

          Can you update https://github.com/SkriptLang/skript-docs/blob/main/README.md as well since it mentions doc-template

Originally posted by @AyhamAl-Ali in #47 (review)

Expression - ExprName | 2 Expressions?

Not sure really what to call this nor how to give a better explanation the site seems to just cut them into 2 expressions instead of as a single one, this might be caused by skript's end of stuff *last image as we register 2 expressions using this class

Links
https://docs.skriptlang.org/expressions.html?search=#ExprName
https://docs.skriptlang.org/expressions.html?search=#ExprName-2
*above one bugs out but it's whats given when you copy link

weird layout bug when cookie banner visible

caused by cookie banner having position: sticky; instead of position: absolute; width: 100%;

[BUG] SkriptLang testing environment syntax is leaking through

Some of SkriptLang's testing environment syntax like CondMethodExists has leaked through and into the release documentations, unsure what else there is that is from it.

Enhancement | EventValues

Suggestion

Add a section for event-values of an event to the docs page.

Why

Whenever you're needing to use an event you aren't always sure what event-values exist without either using process of elimination or looing at source code. Having a little portion saying "Event Values" is a much easier and cleaner for everyone method

Other

I'm not sure how feasible this really is but as SkriptHub has this I figured it would be a good addition to the official docs as well.

The built site should not be committed in the main branch

Built content does not need to be versioned / to be present in source control. This makes it very difficult to track actual modifications made by contributors, as they are mixed in with automated actions. Another important aspect is practicality for developers: committing such a large site to the main branch makes the repository very heavy and time-consuming to pull from what I've been able to experience.

Docs and docs-template need to be in the same folder

The Docs and docs-template need to be in the same folder for easy usage of git with the Skript repo. You can simultaneously work on the Skript repo in conjunction with the docs. Similarly to the aliases. With the aliases you can work in the test_runner folder of the aliases while changing branches.

The folder can be something like

plugins/Skript/documentation/

doc-template -> plugins/Skript/documentation/templates
docs -> plugins/Skript/documentation/output

When utilizing git and the gradle build/ cache folder you can switch between git branches and also be able to clean reset the docs for fresh install test with gradlew clean ...

I don't see a need in making this configurable.

💡 Make searching less trict

e.g. Vectors - Length wouldn't be matched if user searched for vectors length so something like this would easily be fixed by excluding/filtering some symbols from titles (only) as otherwise it may match unexpected results + heavier process. Right now I am thinking of excluding the regex [-/&\(\)]

Thanks to @APickledWalrus for this finding

Issue:

Expectation: (without using -)

💡 Inlude Event Cancellable Section for Events

🖐️

⚒ og:image using wrong link

og:image should be using this link https://docs.skriptlang.org/assets/icon.png

This causes link embed missing the image

add crouch and shift to the skript docs

Suggestion

add crouch and shift into the searchable terms for sneak because people get confused

Why?

for a while, I and a few other developers did not think there was a sneak event as crouch and shift are more common.

Other

you could add the on shift and on unshift events...

Agreement

• I have read the guidelines above and affirm I am following them with this suggestion.

💡 Accepted changes for expressions in docs

This is a useful information to be added in the docs is to know what are the accepted changes you can do for each expression.

Example

Accepted Changes is a bit too long, could someone suggest a shorter name :)

I will try to push a PR for that as soon as I can.

Issue when selection on sidebar

So whenever you click a sidebar option to auto scroll to that spot after a certain point it stops scrolling and forces you to click the button again

to do this yourself all you got to do is open any area effects, expressions, types, functions, etc....
from my test it stops at these locations

Events : top -> on vehicle exit
Conditions : top > is type of
Effects : top -> title - send
Expressions : top -> whitelist
Types : top -> timeperiod
Functions : top -> product

💡 Bunch of issues and features

Hola!

This is a bunch of issues/features that I will be putting in one issue:

⚒ Issues

• Issue Tracker link in homepage is still using Skript repo not skript-docs repo
• When clicking on Docs tab on phones it will directly visit the docs page instead of showing the hover menu option
• Cookies Bar showing in the wrong place inside documentation pages
• When zooming out the page title text size stays as is and doesn't adapt
• Fix anchor links in Docs page when there are multiple elements sharing same ID

🚀 Features

• Either Edit GitHub tab to Skript Github to add Docs Github or add Docs Github somewhere else
• Show "No new features added since X" instead of "No matches found." when using New page and searching for some version that has no new features
• Add a page for Dev Tools indentifying its purpose (Tools for developers such as javadocs, addon tutorials etc.)
• Add a page for Tutorials page showing all tutorials in boxes with maybe covers and titles (there is much more info on this just not yet published)
• Improve light bulb design (Theme Changer)
• Add copy-to-clipboard icon beside each pattern
• Add bounce with little more shadow under hovered element (maybe - optional)
• Add searching filter guide icon in addition to the current hover text
• Add examples/scripts page for cool/useful/helpful scripts/examples for newcomers
• Add skUnity & Skript Testing Community discord button/box in homepage
• Add more elements/statistics to documentation homepage
• Add Hamburger menu to mobile version
• Adding Heading underline (short/long) class (used mostly in tutorials for better visibility)
• Add small rounded boxes to tutorials showing release/update date, author name at the bottom or top (mostly top)

🐛 Sidebar active item can't active on last element

This just requires the active item 'sensor' (activation space) in JS code to be moved down a little bit

Add translatable tag

add this to the text.html SkriptLang/Skript#5481

🐞 docs.html 2 entries with same id

Bug Description

When using the docs.html? link for documentation, select elements might have the same id and if you attempt to copy the 2nd, it will only link you to the first element of the 2.

How to replicate

Go to the docs.html? page and search in world, go to the function 'world' all the way down and click copy link

404 on https://docs.skriptlang.org/strings/

The link is on this page: https://docs.skriptlang.org/classes.html#string

🐛 Function structure pattern is not user friendly

🐛 Search bar element ID is case sensitive

Issue with location

Just updated to the last version which is 2.7.0 beta2 and found this issue. Console says that I don't have a location in the command event but next to that is the skript i'm using that clearly shows the location. How do I fix this or should I revert back to a earlier version.