Discover Reference Guide

↩ Up

Preface

The supported way to integrate discover with your website is with hugo. It’s still possible to set up discover without hugo but will require a little more effort until a script is made.

How It Works

Any peer can host an html snippet which is their preview banner. This “profile card” will be displayed on other peer’s sites who want to share your work. Cross origin resource sharing will be enabled.

Any peer can have one or more lists of previews which can be labeled by topic. The previews are loaded with htmx. Websites which do not yet support discover should not be added to your previews.

In either case, the setup is minimal and flexible.

Server

Make Your Preview

This is optional. If you just want to setup a directory displaying previews, then go to the client setup section.

First, create your preview file.

mkdir static/.well-known && touch static/.well-known/discover

There’s up to four fields to fill in:

- Your website's url
- A short description (optional)
- Url to your profile picture
- The website's name

Copy and paste this html into static/.well-known/discover, and swap in your info.

<a href="https://example.org" title="My description" >
    <img src="https://example.org/path/to/profile/pic.webp">
    <span>My Name</span>
</a>

Allow CORS

Copy and paste this nginx snippet into your website’s configuration. It will enable your web server to accept ajax requests.

location /.well-known/discover {
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Headers' '*';
        add_header 'Access-Control-Max-Age' 1728000;
        add_header 'Content-Type' 'text/plain; charset=utf-8';
        add_header 'Content-Length' 0;
        add_header Vary Origin;
        return 204;
    }
    if ($request_method = 'GET') {
	add_header 'Access-Control-Allow-Origin' '*' always;
	add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
	add_header 'Access-Control-Allow-Credentials' 'true';
	add_header 'Access-Control-Allow-Headers' '*';
	add_header Content-Type text/html;
    }
}

Reload nginx:

systemctl reload nginx

If you want your site to be previewed but not have a directory, you may stop here.

Client

Security

Although discover is based on trust, there are some security measures we can put in place for peace of mind.

Copy and paste this nginx snippet into your website’s configuration.

# Change 'links' to the name of the page discover is on
location /links/ {
#   Blocks inline js. Prevents xss attacks. Change 'self' if you use third party js
    add_header 'Content-Security-Policy' "script-src 'self';";
#   Blocks inline css. Prevents trolling. May break things if you use inline css.
    add_header 'Content-Security-Policy' "style-src 'self';";
}

Reload nginx:

systemctl reload nginx

Previews

In hugo’s data directory, make a new folder for discover previews.

mkdir data/discover && cd data/discover

Now make a new toml file (the name is unimportant) to store previews on a certain topic. You can make as many files as you’d like.

topic = "Placeholder Sites"
previews = [
    'example.org',
    'another.org',
    'yetanother.org'
]

Go up to your hugo directory and download htmx.min.js (it’s 12kb gzip’d).

cd ../..
curl https://unpkg.com/htmx.org@1.8.6/dist/htmx.min.js -o static/htmx.js

Shortcode

Copy and paste the following shortcode into layouts/shortcodes/discover.html.

<div id="discover">
<script src="/htmx.js"></script>
<link rel="stylesheet" href="/css/discover.css"></link>
<noscript><link rel="stylesheet" href="/css/no-js.css"></noscript>
{{ range .Site.Data.discover }}
    <h3>{{ .topic }}</h3>
    <ul>
    {{ range .previews }}
    <li>
        <div
        hx-get="https://{{ . }}/.well-known/discover"
        hx-trigger="load"
        hx-swap="outerHTML"></div>
    </li>
    {{ end }}
    </ul>
{{ end }}
<em>Powered by <a href="https://onasaft.codeberg.page/discover">Discover</a></em>
</div>

Now you can call that shortcode which builds your directory from any content file. Just include this snippet:

{{< discover >}}

Styling

Here’s the css from the demo to get you started. Copy and paste into static/css/discover.css.

:root {
	/* Link Colors for Light Theme */
        --links: royalblue;
        --hover: navy;
	/* Directory Colors for Light Theme*/
        --dbg: #eee;
        --dfg: #ddd;
        --dhl: #ccc;
}
@media (prefers-color-scheme: dark) {
    :root {
	    --links: lightskyblue;
	    --hover: azure;
	    --dbg: #2c2c2c;
	    --dfg: #353535;
	    --dhl: #555;
    }
}

#discover header,footer,h1,h2,h3,h4{font-family: c059, sans-serif}

#discover {
    padding: 1rem;
    background: var(--dbg);
    border-radius: 5px;
}
#discover h3 {text-align: center}
#discover img {
    max-width: 10rem;
    max-height: 10rem;
    border-radius: 10rem;
}
#discover ul {
    display: flex;
    flex-direction: row;
    align-items: flex-end;
    justify-content: flex-start;
    flex-wrap: wrap;
}
#discover li {list-style-type: none}
#discover li a {
    text-align:center;
    padding: 1rem;
    margin: 0.5rem;
    border-radius: 2px;
    display: flex;
    flex-direction: column;
    background: var(--dfg);
    min-height: 220px;
}
#discover li a:hover {background: var(--dhl);}
#discover li a span{
    color: var(--links);
    font-weight: bold;
    padding-top: 1em;
    max-width: 160px;
}
#discover a:hover{color: var(--hover)}

If js is disabled, we should not display the directory. Copy and paste the following into static/css/no-js.css

#discover {display:none}

That’s it!

It’s left as an excercise to those with a different ssg to write a plugin supporting the discover project specification. Reach out and your work may be shared here.