shareon/docs/index.html

338 lines
12 KiB
HTML
Raw Normal View History

2020-03-25 11:45:04 -04:00
<!DOCTYPE html>
<html lang="en">
2022-02-08 12:56:39 -05:00
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta
name="description"
content="Lightweight, stylish and ethical share buttons for popular social networks"
/>
<meta
name="keywords"
content="share buttons, sharing, social networks, share via, share on"
/>
<meta name="author" content="Nikita Karamov" />
<title>shareon Lightweight, stylish and ethical share buttons</title>
2020-03-25 11:45:04 -04:00
2022-02-08 12:56:39 -05:00
<meta property="og:title" content="shareon" />
<meta property="og:url" content="https://shareon.js.org" />
<meta
property="og:image"
content="https://raw.githubusercontent.com/kytta/shareon/main/assets/banner.png"
/>
<meta
property="og:description"
content="Lightweight, stylish and ethical share buttons for popular social networks"
/>
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:creator" content="@KyttaWasHere" />
<link
rel="stylesheet"
href="https://igoradamenko.github.io/awsm.css/css/awsm.min.css"
/>
2020-03-25 20:43:21 -04:00
<style>
2022-02-08 12:56:39 -05:00
.shareon > a:hover {
color: #fff;
}
2020-03-25 20:43:21 -04:00
2022-02-08 12:56:39 -05:00
button:not([disabled]):hover {
border: none;
}
</style>
2020-03-25 20:50:23 -04:00
2022-02-08 12:56:39 -05:00
<link rel="manifest" href="/site.webmanifest" />
<link rel="icon" href="/favicon.ico" />
<link rel="icon" href="/icon.svg" type="image/svg+xml" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
</head>
<body>
2020-03-25 11:45:04 -04:00
<header>
2022-02-08 12:56:39 -05:00
<p>
<img
src="https://raw.githubusercontent.com/NickKaramoff/shareon/main/assets/logo.svg"
alt="shareon logo — the Postal Horn emoji"
width="64"
height="64"
/>
</p>
<h1>shareon</h1>
<p>Lightweight, stylish and ethical share buttons</p>
<nav>
<ul>
<li>
<a href="https://www.npmjs.com/package/shareon" target="_blank"
>npm</a
>
</li>
<li>
<a href="https://github.com/kytta/shareon" target="_blank"
>github</a
>
</li>
</ul>
</nav>
2020-03-25 11:45:04 -04:00
</header>
<main>
2022-02-08 12:56:39 -05:00
<article>
<h2>
<a id="what-is-it" href="#what-is-it" aria-hidden="true"></a>
What is it?
</h2>
<p>
<code>shareon</code> are share buttons for popular social networks.
</p>
<div
class="shareon"
data-title="shareon — lightweight, stylish and ethical share buttons"
style="text-align: center"
>
<a class="facebook"></a>
<a class="linkedin"></a>
<a class="mastodon" data-via="@kytta@fosstodon.org"></a>
<a class="messenger" data-fb-app-id="3619024578167617"></a>
<a class="odnoklassniki"></a>
<a class="pinterest"></a>
<a class="pocket"></a>
<a class="reddit"></a>
<a class="telegram"></a>
<a class="twitter" data-via="KyttaWasHere"></a>
<a class="viber"></a>
<a class="vkontakte"></a>
<a class="whatsapp"></a>
</div>
<p>Unlike many other share buttons, <code>shareon</code> are:</p>
<ul>
<li>
<b>lightweight</b>, clocking in at only 6 KB gzipped code (JS+CSS)
</li>
<li>
<b>stylish</b>, by having no visual features other than official
colors and logos
</li>
<li>
<b>ethical</b>, since they do not insert any pesky tracking code
</li>
</ul>
<p>
The whole JavaScript code is quick and simple: it only populates the
buttons with set up links. The speed and easy customization make
<code>shareon</code> the perfect choice for your blog, news site or
project page!
</p>
</article>
<article>
<h2>
<a id="install" href="#install" aria-hidden="true"></a>
Install
</h2>
<p>Include the link to shareon's JS and CSS in your website:</p>
<pre><code>&lt;link href="https://cdn.jsdelivr.net/npm/shareon@1/dist/shareon.min.css"
2020-03-25 20:43:21 -04:00
rel="stylesheet"&gt;
2020-07-30 05:58:57 -04:00
&lt;script src="https://cdn.jsdelivr.net/npm/shareon@1/dist/shareon.min.js"
2020-03-25 20:43:21 -04:00
type="text/javascript"&gt;&lt;/script&gt;</code></pre>
2022-02-08 12:56:39 -05:00
<p>
or install it via NPM and use it in a JS file that you will later
bundle:
</p>
<pre><code>const shareon = require('shareon');</code></pre>
<pre><code>import shareon from 'shareon';</code></pre>
</article>
<article>
<h2>
<a id="initialization" href="#initialization" aria-hidden="true"></a>
Initialization
</h2>
<p>
By default, shareon will initialize every button after page load. It
also exports the <code>shareon</code> function, that will let you
repopulate your buttons with updated information (for example, if you
changed the page title):
</p>
<pre><code>// shareon auto-initializes
2020-07-26 08:40:37 -04:00
window.title = "Cool new window title";
shareon();</code></pre>
2022-02-08 12:56:39 -05:00
<p>
If you want to postpone the initialization, you can import the
<code>noinit</code>-version of the package. You'll need to manually
call the <code>shareon</code> function when you want the buttons to be
initialized:
</p>
<pre><code>&lt;!-- notice the 'noinit' section of the url for JS --&gt;
2020-07-30 05:58:57 -04:00
&lt;script src="https://cdn.jsdelivr.net/npm/shareon@1/dist/noinit/shareon.min.js"
2020-07-26 08:40:37 -04:00
type="text/javascript"&gt;&lt;/script&gt;
2020-07-30 05:58:57 -04:00
&lt;link href="https://cdn.jsdelivr.net/npm/shareon@1/dist/shareon.min.css"
2020-07-26 08:40:37 -04:00
rel="stylesheet"&gt;
&lt;script type="text/javascript"&gt;
// do something important
shareon();
&lt;/script&gt;</code></pre>
2022-02-08 12:56:39 -05:00
<p>or, if you're using Node:</p>
2020-07-26 08:40:37 -04:00
2022-02-08 12:56:39 -05:00
<pre><code>const shareon = require('shareon');
2020-07-26 08:40:37 -04:00
// or
import shareon from 'shareon';
// do something important
shareon();</code></pre>
2022-02-08 12:56:39 -05:00
</article>
<article>
<h2>
<a id="usage" href="#usage" aria-hidden="true"></a>
Usage
</h2>
<aside>
<p>
<code>shareon</code> was heavily inspired by
<a href="https://ilyabirman.net/projects/likely/">Likely</a>, and
has a backwards-compatible API
</p>
</aside>
<p>
Create a container with class <code>shareon</code> and populate it
with elements, whose classes match the names of social networks:
</p>
<pre><code>&lt;div class="shareon"&gt;
2020-03-25 20:43:21 -04:00
&lt;a class="facebook"&gt;&lt;/a&gt;
&lt;a class="linkedin"&gt;&lt;/a&gt;
&lt;a class="mastodon"&gt;&lt;/a&gt;
2020-09-28 07:48:10 -04:00
&lt;!-- FB App ID is required for the Messenger button to function --&gt;
&lt;a class="messenger" data-fb-app-id="0123456789012345"&gt;&lt;/a&gt;
2020-03-26 17:45:42 -04:00
&lt;a class="odnoklassniki"&gt;&lt;/a&gt;
2020-03-25 20:43:21 -04:00
&lt;a class="pinterest"&gt;&lt;/a&gt;
&lt;a class="pocket"&gt;&lt;/a&gt;
&lt;button class="reddit"&gt;&lt;/button&gt;
2020-06-26 11:27:59 -04:00
&lt;button class="telegram"&gt;&lt;/button&gt;
&lt;button class="twitter"&gt;&lt;/button&gt;
&lt;button class="viber"&gt;&lt;/button&gt;
2020-06-26 11:27:59 -04:00
&lt;button class="vkontakte"&gt;&lt;/button&gt;
&lt;button class="whatsapp"&gt;&lt;/button&gt;
2020-03-25 20:43:21 -04:00
&lt;/div&gt;</code></pre>
2022-02-08 12:56:39 -05:00
<div class="shareon">
<a class="facebook"></a>
<a class="linkedin"></a>
<a class="mastodon"></a>
<a class="messenger" data-fb-app-id="3619024578167617"></a>
<a class="odnoklassniki"></a>
<a class="pinterest"></a>
<a class="pocket"></a>
<button class="reddit"></button>
<button class="telegram"></button>
<button class="twitter"></button>
<button class="viber"></button>
<button class="vkontakte"></button>
<button class="whatsapp"></button>
</div>
<p>
If you use <code>&lt;a&gt;</code>, the buttons will get a
`href`-attribute to them. In other cases they will get a listener on
<code>click</code> event, so you can use <code>&lt;button&gt;</code>s
if you wish.
</p>
<p>
By default, the URL and the title of the page will be used in sharing
dialogs. To change this, you can use the <code>data-url</code> and
<code>data-title</code> attributes. Use them on the whole container or
on the specific buttons:
</p>
<pre><code>&lt;div class="shareon" data-url="https://example.com"&gt;
2020-03-26 18:04:39 -04:00
&lt;a class="whatsapp" data-title="Custom WhatsApp title"&gt;&lt;/a&gt;
2020-03-25 20:43:21 -04:00
&lt;a class="twitter" data-title="Custom Twitter title"&gt;&lt;/a&gt;
&lt;/div&gt;</code></pre>
2022-02-08 12:56:39 -05:00
<div class="shareon" data-url="https://example.com">
<a class="whatsapp" data-title="Custom WhatsApp title"></a>
<a class="twitter" data-title="Custom Twitter title"></a>
</div>
2020-03-25 20:43:21 -04:00
2022-02-08 12:56:39 -05:00
<p>
Apart from the URL and title, some networks support extra parameters:
</p>
2020-03-25 20:43:21 -04:00
2022-02-08 12:56:39 -05:00
<ul>
<li>
you <strong>have to</strong> add <code>data-fb-app-id</code> to the
FB Messenger button to make sharing even possible
</li>
<li>
add <code>data-media</code> to an Odnoklassniki, Pinterest, or VK
button to customize the pinned picture
</li>
<li>
add <code>data-text</code> to a WhatsApp, Mastodon, Telegram, or
Viber button to add custom message text
</li>
<li>
add <code>data-via</code> to a Twitter or Mastodon button to mention
a user
</li>
</ul>
<p>Here are all the custom parameters in their glory:</p>
<pre><code>&lt;div class="shareon" data-url="https://example.com/custom-url"&gt;
2020-03-25 20:43:21 -04:00
&lt;a class="facebook" data-title="Custom Facebook title"&gt;&lt;/a&gt;
2020-09-28 07:48:10 -04:00
&lt;a class="messenger" data-fb-app-id="0123456789012345"&gt;&lt;/a&gt;
2020-03-25 20:43:21 -04:00
&lt;a class="pinterest" data-media="https://picsum.photos/500"&gt;Pin&lt;/a&gt;
&lt;a class="telegram" data-text="Check this out!"&gt;&lt;/a&gt;
&lt;a class="twitter" data-via="MyNickname"&gt;&lt;/a&gt;
2020-09-28 08:01:29 -04:00
&lt;a class="mastodon" data-via="@MyNickname@myserver.social"&gt;&lt;/a&gt;
2020-09-28 07:48:10 -04:00
&lt;a class="whatsapp" data-url="https://my-cool-website.com"&gt;Send&lt;/a&gt;
2020-03-25 20:43:21 -04:00
&lt;/div></code></pre>
2022-02-08 12:56:39 -05:00
<div class="shareon" data-url="https://example.com/custom-url">
<a class="facebook" data-title="Custom Facebook title"></a>
<a class="messenger" data-fb-app-id="3619024578167617"></a>
<a class="pinterest" data-media="https://picsum.photos/500">Pin</a>
<a class="telegram" data-text="Check this out!"></a>
<a class="twitter" data-via="MyNickname"></a>
<a class="mastodon" data-via="@MyNickname@myserver.social"></a>
<a class="whatsapp" data-url="https://my-cool-website.com">Send</a>
</div>
</article>
2020-03-25 11:45:04 -04:00
</main>
<footer>
2022-02-08 12:56:39 -05:00
<p>
by <a href="https://www.kytta.dev/" target="_blank">Nikita Karamov</a>
</p>
<p>
Website built with
<a
href="https://igoradamenko.github.io/awsm.css/index.html"
target="_blank"
>awsm.css</a
>
</p>
2020-03-25 11:45:04 -04:00
</footer>
2020-03-25 20:43:21 -04:00
2020-09-24 14:28:13 -04:00
<!-- These files are autocopied on build and will be present on the website -->
<!-- See https://github.com/kytta/shareon/blob/main/.github/workflows/node.yml#L29 -->
2022-02-08 12:56:39 -05:00
<link href="shareon.min.css" rel="stylesheet" />
2020-09-24 14:28:13 -04:00
<script src="shareon.min.js" type="text/javascript"></script>
2022-02-08 12:56:39 -05:00
</body>
2020-03-25 20:43:21 -04:00
</html>