From 06bf686f8c08b6c6208f7ca153604387fbc5958c Mon Sep 17 00:00:00 2001 From: Theis Pieter Hollebeek Date: Mon, 13 Oct 2025 17:10:00 +0200 Subject: [PATCH] improve docs rendering --- docs/src/gamelib/index.md | 4 +- docs/src/gamelib/other.md | 256 +------------------------------------- docs/src/index.md | 2 + docs/static/headers.js | 24 ++-- docs/static/style.css | 69 ++++++---- 5 files changed, 66 insertions(+), 289 deletions(-) diff --git a/docs/src/gamelib/index.md b/docs/src/gamelib/index.md index 9e96182..cdbcf8d 100644 --- a/docs/src/gamelib/index.md +++ b/docs/src/gamelib/index.md @@ -1,7 +1,5 @@ # Gamelib -## Contents - ## Models @@ -78,7 +76,7 @@ The name used for `deltaT` can be anything, it functions as any other function p For example: -``` +```js loopFunction is called at 12:00.24 - deltaT is 0 loopFunction is called at 12:00.75 - deltaT is .51 loopFunction is called at 12:01.52 - deltaT is .77 diff --git a/docs/src/gamelib/other.md b/docs/src/gamelib/other.md index 765a331..af7e789 100644 --- a/docs/src/gamelib/other.md +++ b/docs/src/gamelib/other.md @@ -1,259 +1,7 @@ # Gamelib -## Contents - -## Models - -### `Color` - -A type of string. - -Represents HTML colors. This includes -[named colors](https://developer.mozilla.org/en-US/docs/Web/CSS/named-color) such as `blue`, `red`, -`blanchedalmond`, `lavenderblush`, and rgb/hex when used with proper format. You can use -[`lib.rgb(r,g,b)`](#Lib-rgb) to generate a properly formatted rgb color code. - -Example: - -```ts -lib.drawRect(0, 0, 100, 100, "blue"); -lib.drawRect(100, 0, 100, 100, lib.rgb(192, 127, 172)); -``` - -### `Key` - -A type of string. - -Represents JavaScript's -[`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) property. - -Example: - -``` -"Enter": Enter was pressed. -"b": Lowercase 'b' was pressed. -"B": Uppercase 'B' was pressed (i.e. Shift + B) -" ": Spacebar was pressed. -``` - -/* todo: include a little html tool that listens to key events when focused and outputs what key was -pressed */ - -### `KeyEventFunc` - -A function with no parameters that is called whenever the appropriate [`Key`](#Models-Key) is -pressed / released. - -Works both as a named and anonymous function. - -Example: - -```ts -let playerX = 0; - -// anonymous function -lib.onPress("a", function () { - playerX -= 20; -}); - -// named function -function dWasPressed() { - playerX += 20; -} -// note the lack of () after dWasPressed - we are not calling the function, we are referring to it as a variable -lib.onPress("a", dWasPressed); -``` - -### `LoopFunc` - -A function with a single parameters (`deltaT`) that is called whenever a game tick should run - -usually about 1/60 times a second. - -The `deltaT` parameter describes the time difference between the last tick and now, in seconds. - -The name used for `deltaT` can be anything, it functions as any other function parameter. I.e. -`loopFunction(timeSinceLastCall)`, `loopFunction(fooBar)`, etc. - -For example: - -``` -loopFunction is called at 12:00.24 - deltaT is 0 -loopFunction is called at 12:00.75 - deltaT is .51 -loopFunction is called at 12:01.52 - deltaT is .77 -``` - -Works both as a named and anonymous function. - -Example: - -```ts -let playerX = 0; - -// anonymous function -lib.startGameLoop(function (deltaT) { - playerX += 20 * deltaT; -}); - -// named function -function loopFunction(deltaTime) { - playerX += 20 * deltaTime; -} -// note the lack of () after loopFunction - we are not calling the function, we are using it as a variable -lib.startGameFunction(loopFunction); -``` - -## Lib - -### `println` - -`lib.println(msg: string) -> void` - -Print a message the debug console. - -Example: - -```ts -lib.println("Hello world!"); -lib.println("It is a thursday."); -``` - -```ini -[console] -Hello world! -It is a thursday. -``` - -### `startGameLoop` - -`lib.startGameLoop(loopFunction: LoopFunc) -> void` - -Registers a gameloop function, that is called on every tick. - -See also: [`Models.LoopFunc`](#Models-LoopFunc) - -### `isPressed` - -`lib.isPressed(key: Key) -> bool` - -Returns whether or not `key` is currently pressed. - -See also: [`Models.Key`](#Models-Key) - -Example: - -```ts -let playerX = 0; -lib.startGameLoop(function (deltaT) { - if (lib.isPressed("a")) { - playerX -= 20 * deltaT; - } - if (lib.isPressed("d")) { - playerX -= 20 * deltaT; - } -}); -``` - -### `onPress` - -`lib.onPress(key: Key, handlerFunction: KeyEventFunc) -> void` - -Calls `handlerFunction` whenever `key` is pressed. - -See also: [`Models.Key`](#Models-Key), [`Models.KeyEventFunc`](#Models-KeyEventFunc) - -Example: - -```ts -let isJumping = false; - -lib.onPress(" ", function () { - isJumping = true; -}); - -lib.onRelease(" ", function () { - isJumping = false; -}); -``` - -### `onRelease` - -`lib.onRelease(key: Key, handlerFunction: KeyEventFunc) -> void` - -The opposite of [`lib.onPress`](#Lib-onPress) - -### `rgb` - -`lib.rgb(red: number, green: number, blue: number) -> Color` - -Generates a correctly formatted [`Color`](#Models-Color) value based on `red`, `green` and `blue` - -See also: [`Models.Color`](#Models-Color) - -Example: - -```ts -lib.drawRect(100, 0, 100, 100, lib.rgb(192, 127, 172)); -``` - -### `clear` - -`lib.clear(color: Color) -> void` - -Paints the entire screen `color`. - -See also: [`Models.Color`](#Models-Color) - -Example: - -```ts -function drawClouds() { - /* some lib.drawRect(..) or lib.drawSprite(..) */ -} - -lib.startGameLoop(function () { - lib.clear("blue"); - drawClouds(); -}); -``` - -### `drawSprite` - -`lib.drawSprite(x: number, y: number, width: number, height: number, name: string) -> void` - -Draws a sprite imported in the sprite editor. - -/* todo: link to sprite editor docs */ - -Example: - -```ts -lib.startGameLoop(function () { - lib.clear("blue"); - lib.drawSprite(20, 30, 20, 10, "cloud.png"); -}); -``` - -### `drawRect` - -`lib.drawRect(x: number, y: number, width: number, height: number, color: Color) -> void` - -Fills a rect with [`Color`](#Models-Color). - -See also: [`Models.Color`](#Models-Color) - -Example: - -```ts -function drawCloud(x, y) { - lib.drawRect(x, y, 20, 10, "white"); -} - -lib.startGameLoop(function () { - lib.clear("blue"); - drawCloud(20, 30); - drawCloud(50, 35); -}); -``` +## What is this? +Example of having two .md files in the same directory diff --git a/docs/src/index.md b/docs/src/index.md index 781e138..5dbd341 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,5 +1,7 @@ # Docs + + ## Gamelib [Link to Gamelib docs](gamelib) diff --git a/docs/static/headers.js b/docs/static/headers.js index a46d7a2..4b28097 100644 --- a/docs/static/headers.js +++ b/docs/static/headers.js @@ -12,9 +12,6 @@ function renderTableOfContents() { const ancestors = []; for (const header of headers) { - if (header.textContent === "Contents") { - continue; - } const depth = parseInt(header.tagName.slice(1)) - 1; while (ancestors.length >= depth) { ancestors.pop(); @@ -40,15 +37,20 @@ function renderTableOfContents() { ancestors.push(ul); } - root.replaceChildren(list); + const title = document.createElement("h2"); + title.textContent = "Table of contents"; + + root.replaceChildren(title, list); } -function groupHeadersInDiv(headerTag) { - const firstElement = document.querySelector(headerTag); - if (firstElement === null) { +function groupHeadersInDiv(headerTag, index = 0) { + const elements = document.querySelectorAll(headerTag); + const firstElement = elements[index]; + if (!firstElement) { return; } let container = document.createElement("div"); + console.log(firstElement); firstElement.replaceWith(container); container.append(firstElement); @@ -60,9 +62,13 @@ function groupHeadersInDiv(headerTag) { if (sib.nodeName === headerTag.toUpperCase()) { container = document.createElement("div"); sib.replaceWith(container); + index++; } container.append(sib); } + if (index < elements.length) { + groupHeadersInDiv(headerTag, index + 1); + } } function slugify(elements) { @@ -90,4 +96,6 @@ function attachIdToHeaders() { attachIdToHeaders(); renderTableOfContents(); -groupHeadersInDiv("h2"); +for (let i = 2; i <= 6; ++i) { + groupHeadersInDiv(`h${i}`); +} diff --git a/docs/static/style.css b/docs/static/style.css index cc68e8e..0d8759b 100644 --- a/docs/static/style.css +++ b/docs/static/style.css @@ -28,22 +28,14 @@ body { padding: 1rem; max-width: 1000px; margin: 0 auto; + line-height: 1.5; } -h1 { - font-size: 2.5rem; -} - -h2 { - font-size: 2rem; -} - -h3 { - font-size: 1rem; -} - -h4 { - font-size: 0.5rem; +h1, h2, h3, h4, h5, h6 { + line-height: 1; + code { + font-size: inherit; + } } a { @@ -68,16 +60,21 @@ h1, h2, h3, h4, h5, h6 { isolation: isolate; position: relative; max-width: max-content; + + background: var(--clr-bg-1); + + border-radius: 0 0.5rem 0.5rem 0; + padding: 0.5em; &::before { content: ""; position: absolute; - top: -0.25em; - bottom: -0.25em; - right: -1em; - left: -10rem; + width: 3em; + top: 0; + bottom: 0; + left: -3em; z-index: -1; - border-radius: 0.5rem; - background: linear-gradient(to left, var(--clr-bg-1) 75%, transparent); + background: linear-gradient(to left, var(--clr-bg-1), transparent); + border-radius: 0.5rem 0 0 0.5rem; } } @@ -87,8 +84,32 @@ h2 { z-index: 10; } -table-of-contents > ul { - list-style: none; - padding-left: 0; - font-size: 1.25rem; +table-of-contents h2 { + position: initial; +} + +table-of-contents { + background: var(--clr-bg-1); + border-radius: 0.5rem; + padding: 1.5rem; + display: block; + max-width: max-content; +} + +table-of-contents ul:first-of-type { + font-size: 1.1em; + padding-left: 1.5rem; + margin: 0; +} + +table-of-contents li: { + margin-bottom: 0.25em; +} + +table-of-contents h2 { + padding-inline: 0; + margin: 0; + &::before { + all: initial; + } }