Linkshuffle Docs
2/4/2023
Figure out how Linkshuffle works.
Back
NoteThis is the more technical documentation of Linkshuffle. Currently, there isn't an easy way to use this if you're not knowledgeable with Javascript.
Quickstart
Wanna make your own list of links? You should change the
ls-list
configuration property by directly modifying the file. Soon, I would like to make a generator.Modifying Linkshuffle
There are three ways to modify Linkshuffle's configuration.
Query parameters
Great for easily modifying the look of Linkshuffle when embedding it. Simply add the configuration to the URL like so:
https://dabric.xyz/linkshuffle.min.html?lsstyle-foreground=lime&lsstyle-background=darkslategrey
Attributes
WarningYou have to host Linkshuffle yourself. If you hotlink from my website, it won't do anything.
Great for dynamically modifying the configuration with JavaScript. Simply add the configuration using
data-
attributes:- js
<iframe src="https://dabric.xyz/linkshuffle.min.html" frameborder="0" title="linkshuffle"></iframe> <script> const frame = document.querySelector("iframe"); let hue = 0; setInterval(() => { hue += 5 hue %= 360 const color = `hsl(${hue}deg, 100%, 50%)`; frame.setAttribute("data-lsstyle-foreground", color) frame.setAttribute("data-lsstyle-overlay-foreground", color) frame.setAttribute("data-lsstyle-outline-color", color) }, 100); </script>
Directly modifying the file
Great for distributing your own collection of links. Download the unminified version, and scroll to the bottom of the HTML file. You'll want to add a
script
tag:- html
... } window.dispatchEvent(new CustomEvent("ls-loaded")); })(); }); </script> <script> // Here. </script> </body> </html>
In your script tag, listen for the
ls-loaded
event on the window. Here, use the setConfig()
function exposed in the global scope to modify Linkshuffle's config.- html
<script> window.addEventListener("ls-loaded", () => { setConfig("ls-showtitle", "false"); setConfig("ls-list", "url!https://example.com/links.json"); setConfig("lsstyle-foreground", "black"); setConfig("lsstyle-background", "white"); }); </script>
Configuration
Linkshuffle has two types of configuration: style and data. The main difference is how they're managed. Style uses CSS variables, while data uses JavaScript. Both can be easily modified, as shown above.
Data configuration
ls-delay
The amount of time in milliseconds between links. Set it to
0
to disable automatically switching.Default:
10000
(10 seconds)ls-showrandombutton
Whether or not to show the random button. The random button lets the user switch to another link upon click.
Default:
true
ls-showtitle
Whether or not to show the title of the link at the top left upon hover.
Default:
true
ls-list
The list of links in JSON. View the format here.
You can also provide a URL for Linkshuffle to fetch the JSON from. Give the link with
url!
at the start. For example: url!https://example.com/links.json
.Default:
null
(no links)ls-brandname
The text for the bottom right Linkshuffle watermark.
Default:
linkshuffle
ls-brandnamesmall
Like
ls-brandname
, but for when the mouse isn't hovering.Default:
lnkshfl
ls-brandlinklocation
Where the bottom right Linkshuffle watermark goes to.
If you change this, it would be nice if you gave me some credit somewhere other than the MIT license. Like a "Powered By Linkshuffle" or something on the page the link goes to?
Default:
https://dabric.xyz/post/linkshuffle/
ls-anchorbottom
Anchors the bottom menu so it doesn't obscure the image. The height is set by
lsstyle-anchor-height
.Default:
false
ls-removeonerror
Temporarily removes an image when it fails to load, or the entire link if none of the images work.
Default:
true
ls-compatibilityredirect
Redirects to an earlier version of Linkshuffle if the link list format is too old for it. This only happens when the link list is supplied with
url!
.Default:
true
if detected to be hosted on my website, false
if not.Style configuration
lsstyle-background
Default:
black
lsstyle-foreground
The foreground color.
Default:
white
.lsstyle-overlay-background
The background color for the overlays, which are the things that go on top of the image.
Default:
black
lsstyle-overlay-foreground
The foreground color for the overlays, which are the things that go on top of the image.
Default:
white
lsstyle-outline-color
The color used for outlines.
Default:
#808080
lsstyle-title-bar-shift
How much the title bar slides in upon hover.
Default:
25px
NoteOn systems with reduced motion turned on, this option is forced to zero.
lsstyle-menu-bar-shift
How much the menu bar slides in upon hover. This may make sense to set to zero when there is no short brand name provided.
Default:
25px
NoteOn systems with reduced motion turned on, this option is forced to zero.
lsstyle-font
The font.
Default:
sans-serif
lsstyle-font-size
The font size.
Default:
1em
lsstyle-padding
The amount of padding (empty space).
Default:
5px
lsstyle-outline-thickness
How thick the outlines are. Set it to
0px
to get rid of them.Default:
2px
lsstyle-border-radius
How much corners are rounded off.
Default:
5px
lsstyle-anchor-height
The height of the bottom menu when
ls-anchorbottom
is set to true
.Default:
calc(1em + var(--padding) * 2)
Hosting
You can download Linkshuffle for your own use to get around cross-site madness. Just keep in mind of the MIT license at the top of the file.
- Download the minified version (small but unreadable)
- Download the unminified version (large but readable)
Link list format
A list of links are in JSON, with the following format. Everything is optional, but it's highly recommended to fill them all out.
- json
// linkshuffle has basic json comment support. // use `//`. only an entire line may be a comment. // so, this will result in a syntax error: // "name": "dabric", // comment // but this wont: // // comment // "name": "dabric", { // the version of this format. if linkshuffle detects // an older version, it'll automatically redirect to // said older version if `ls-compatibilityredirect` // is true. "version": 1, "links": [ // an example link. it'll be picked at random. { // the version of this format for this specific // link. you don't need this when you're // directly putting in links like this; it's // intended for when you reference a url. "version": 1, // the name of the link. // - will be shown on hover, unless ls-showtitle // is set to false. // - will also be shown in place of the image if // there isn't one, or if it fails to load. "name": "dabric", // the images to use. it'll be picked at random. "images": [ // an example image. you can have // an unlimited number of them. { // the link to the image. "src": "https://dabric.xyz/dabric.png", // the alt text for the image. "alt": "a short tv-head robot." } ], // the link. "url": "https://dabric.xyz" }, // you can also give a url to a link like this. "https://dabric.xyz/me.json" ] }