Add dir listing, upd. README, add maxcdn-linked files

.github/workflows/main.yml

@@ -21,8 +21,9 @@ jobs:
         sudo apt install -y software-properties-common
         sudo add-apt-repository ppa:deadsnakes/ppa
         sudo apt update
-        sudo apt install -y python3.10 wget tar p7zip
+        sudo apt install -y python3.10 tree wget tar xz p7zip
         python3.10 ./Build.py
+        python3.10 ./Tools/BuildCSS.py --Output="maxcdn" --URLPrefix="https://twemoji.maxcdn.com/v/latest/svg/"
         ./Tools/DeployPages.sh
 
     - name: Deploy

.gitlab-ci.yml

@@ -2,12 +2,13 @@ image: alpine:latest
 
 before_script: |
   apk update
-  apk add python3 wget tar p7zip
+  apk add python3 tree wget tar xz p7zip
 
 pages:
   stage: deploy
   script: |
-    python3.10 ./Build.py
+    python3 ./Tools/BuildCSS.py
+    python3 ./Tools/BuildCSS.py --Output="maxcdn/" --URLPrefix="https://twemoji.maxcdn.com/v/latest/svg/"
     ./Tools/DeployPages.sh
   artifacts:
     paths:

Comment.css

@@ -5,6 +5,6 @@
 	Built on {BuildTime};
 	Generated {EmojiCount} emoji CSS classes.
 
-	Preamble from https://github.com/SebastianAigner/twemoji-amazing,
+	Original preamble from https://github.com/SebastianAigner/twemoji-amazing,
 	licensed under MIT: https://mit-license.org.
 */

Preamble.css

@@ -10,10 +10,12 @@
 	background-repeat: no-repeat;
 	background-position: center center;
 	background-size: 1em 1em;
+	/* Hide fallback emoji text inside the element itself (hacky) */
+	text-indent: -100vw;
 }
 
-/* Prevent image and fallback text emoji overlap */
-.twa > span {
+/* Hide fallback emoji text inside a nested element (correct) */
+.twa > * {
 	font-size: 0px;
 }
 

README.md

@@ -1,8 +1,85 @@
-### Licenses
+# 🌈 Twemoji Astonishing 😲
 
-License for our scripts: [MIT](https://mit-license.org).
+Like **Font-Awesome, but for [Twitter Emojis](https://github.com/twitter/twemoji)** - and this time, it's astonishing! 😄
+
+Modern replacement for projects like [twemoji-amazing](https://github.com/SebastianAigner/twemoji-amazing), with some quality-of-life improvements:
+
+- Easy support for fallback text emojis
+- Literal emojis as CSS class names, in addition to text names
+
+## Usage
+
+### CSS Variants
+
+You can get your preferred variant of the CSS file for use in your webpages:
+
+- `twemoji-astonishing`: The full package with all the features
+- `twemoji-astonishing.chars`: Only literal emojis used as class names
+- `twemoji-astonishing.names`: Only ASCII names used as class names, like twemoji-amazing
+
+Every variant, of course, has both a pure (`.css`) version, and a minified (`.min.css`) one.
+
+### Getting the Files
+
+For getting the files and using them, you can choose between:
+
+- Hotlinking to the latest file hosted on the Pages branch of the repo:
+  - **Directly**: `https://octtspacc.gitlab.io/twemoji-astonishing/maxcdn/<VARIANT>.css`
+  - (Better) **Using a CDN** like jsDelivr: `https://cdn.jsdelivr.net/gh/octospacc/twemoji-astonishing@gh-pages/<VARIANT>.css`
+
+- Downloading a prebuilt archive containing all the CSS and SVG files, which you can host on your own server:
+  - See file listing [here (GitLab)](https://octtspacc.gitlab.io/twemoji-astonishing/index.html), or [here (GitHub)](https://octospacc.github.io/twemoji-astonishing/index.html); archives are in the "Archives" directory.
+
+### Using the CSS Classes
+
+Just assign the base class (`twa`), an emoji class, and optionally any option class to a new inline element.
+
+#### Size Option Classes
+
+Like for Font-Awesome and Twemoji-Amazing, the following classes can be used to alter emoji sizes:  
+`twa-lg`, `twa-2x`, `twa-3x`, `twa-4x`, `twa-5x`.
+
+#### Emoji classes
+
+Emoji classes can be used in one of 2 forms.
+
+First, an emoji class can be the standard form `twa-emoji-name`; essentially, the ASCII name of the emoji, prefixed by `twa-`.  
+Example:  
+```html
+<span class="twa twa-astonished-face"></span>
+```
+
+You can also (additionally, or exclusively) use literal emojis (always prefixed by `twa-`) as class names.
+Example:  
+```html
+<span class="twa twa-🗿"></span>
+```
+
+Any text inside elements with the `twa` class will be properly hidden via CSS.  
+This means that you are free to write text inside those HTML tags - including emoji characters, that will act as a fallback on unsupported platforms (very old browsers), while also allowing emojis to be copied with other text when that gets selected. In fact, you should do this.  
+Example:  
+```html
+<span class="twa twa-exploding-head">🤯</span>
+```
+
+### Finding emojis
+
+- You can look for emoji names, codes, and characters at [Emoji List](https://unicode.org/emoji/charts/emoji-list.html) by the Unicode Consortium. The names you get from the table correspond to the CSS class names if you remove letter accents, remove special characters, and replace spaces with dashes.
+
+- [Emojipedia](https://emojipedia.org) is also a great resource for finding emoji information - the above, but also much more. For each emoji on the site, the URL names correspond to the CSS class names.
+
+## Building
+
+Running `./Tools/BuildCSS.py` generates all final CSS files. Requires Python >= 3.9.
+
+`./Tools/DeployPages.sh` also does other tasks, like downloading a fresh copy of Twemoji SVG files and creating archives.
+
+## Credits and Licenses
+
+License for Twemoji-Astonishing our scripts, snippets, and documentation: [MIT](https://mit-license.org).
 
 Uses CSS snippets from [twemoji-amazing](https://github.com/SebastianAigner/twemoji-amazing), licensed under [MIT](https://mit-license.org).
 
-The project exists solely on top of [Twemoji](https://twemoji.twitter.com).  
-The graphics are licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0). Please adhere to the [Twemoji attribution requirements](https://github.com/twitter/twemoji#attribution-requirements) when using these emojis.
+The project exists solely on top of [Twemoji](https://twemoji.twitter.com). Their graphics are licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0). Please adhere to the [Twemoji attribution requirements](https://github.com/twitter/twemoji#attribution-requirements) when using these emojis.
+
+The included tools for building the CSS files scrape the latest version of the [emoji-test.txt](https://unicode.org/Public/emoji/) list from the Unicode Consortium. See that for copyright and licensing.

Tools/BuildCSS.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 import argparse
 import os
+import rcssmin
 import unicodedata
 from time import ctime
+from pathlib import Path
 from urllib.request import urlopen
-from Tools import rcssmin
 
 cssmin = rcssmin._make_cssmin(python_only=True)
 
@@ -53,17 +54,13 @@ def GetEmojiMeta(Line):
 
 	return {"Code":Code, "Char":Char, "Name":Name}
 
-def WriteCSS(Emojis, URLPrefix):
+def WriteCSS(Emojis, Output, URLPrefix):
+	Path(Output).mkdir(parents=True, exist_ok=True)
 	with open("Preamble.css", "r") as f:
 		Preamble = f.read() + "\n"
 	with open("Comment.css", "r") as f:
 		Comment = f.read().format(BuildTime=ctime(), EmojiCount=str(len(Emojis)))
 
-	try:
-		os.mkdir("Build")
-	except FileExistsError:
-		pass
-
 	for Type in ["Chars Names", "Chars", "Names"]:
 		CSS = Preamble
 		Line = ""
@@ -87,14 +84,15 @@ def WriteCSS(Emojis, URLPrefix):
 		elif Type == "Names":
 			FileName += ".names"
 
-		with open(f"Build/{FileName}.css", "w") as f:
+		with open(f"{Output}{FileName}.css", "w") as f:
 			f.write(CSS.replace("{CommentBlock}", Comment))
-		with open(f"Build/{FileName}.min.css", "w") as f:
+		with open(f"{Output}{FileName}.min.css", "w") as f:
 			f.write(cssmin(CSS).replace("{CommentBlock}", "\n"+Comment))
 
 def Main(Args):
+	Output = Args.Output if Args.Output else "Build/"
 	EmojiVer = Args.EmojiVer if Args.EmojiVer else "15.0"
-	URLPrefix = Args.URLPrefix if Args.URLPrefix else ""
+	URLPrefix = Args.URLPrefix if Args.URLPrefix else "i/"
 
 	print(f"[I] Getting v{EmojiVer} emoji data")
 	Data = GetEmojiData(EmojiVer)
@@ -102,11 +100,12 @@ def Main(Args):
 	print("[I] Parsing emoji data")
 	Emojis = ParseEmojiData(Data)
 
-	print(f"[I] Writing CSS")
-	WriteCSS(Emojis, URLPrefix)
+	print(f"[I] Writing CSS to: {Output}")
+	WriteCSS(Emojis, Output, URLPrefix)
 
 if __name__ == "__main__":
 	Parser = argparse.ArgumentParser()
+	Parser.add_argument('--Output', type=str)
 	Parser.add_argument('--EmojiVer', type=str)
 	Parser.add_argument('--URLPrefix', type=str)
 

Tools/DeployPages.sh

@@ -9,17 +9,22 @@ mv ./twemoji-master ./twemoji
 
 echo "[I] Preparing Pages build"
 rm -rf ./public
-mkdir -p ./public
+mkdir -p ./public ./public/Archives
 cp ./Build/* ./public/
-cp ./twemoji/assets/svg/* ./Build/
+mkdir -p ./Build/i ./public/i
+cp ./twemoji/assets/svg/* ./Build/i/
+cp ./twemoji/assets/svg/* ./public/i/
+mv ./maxcdn ./public/maxcdn
 
 echo "[I] Making archives"
 mv ./Build ./twemoji-astonishing
-cd ./public
-7z a -mx9 -mmt$(nproc --all) twemoji-astonishing.zip ../twemoji-astonishing
-7z a -mx9 -mmt$(nproc --all) twemoji-astonishing.7z ../twemoji-astonishing
-tar cvJf twemoji-astonishing.tar.xz ../twemoji-astonishing
+cd ./public/Archives
+7z a -mx9 -mmt$(nproc --all) twemoji-astonishing.zip ../../twemoji-astonishing
+7z a -mx9 -mmt$(nproc --all) twemoji-astonishing.7z ../../twemoji-astonishing
+tar cvJf twemoji-astonishing.tar.xz ../../twemoji-astonishing
 cd ..
 
-echo "[I] Cleaning up"
+echo "[I] Final steps"
+tree -I "i|index.html" -H . -o index.html
+cd ..
 rm -rf ./Build ./twemoji ./twemoji-astonishing ./twemoji.tar.gz