Facebook Over-Moderation Workaround

[ebouchut]

Issue

We are currently trying to resolve a Facebook over-moderation issue, where many valid FaceBook posts that contain links to LoopDocs are being marked as SPAM when they are not.

Read this Slack thread thread for more details.

One option we want to investigate to resolve this issue is to use a different DNS domain in links to LoopDocs with a custom domain like loopdocs.org instead of loopkit.github.io in upcoming FaceBook posts.

flowchart TD
    A("https#58;//**loopkit.github.io**/loopdocs/browser/bb-overview/") --> B    
    B("https#58;//**loopdocs.org**/loopdocs/browser/bb-overview/")

Loading

Let's see how we can put this in place.

Action Plan

Here is what to do and how.

What?

We will use the loopdocs.org custom domain instead of the default loopkit.github.io on GitHub Pages.

💡 Custom domains often avoid domain-wide spam penalties.

Once configured, accessing the content via

https://loopdocs.org/something

will make a permanent redirect (301) to

https:/www.loopdocs.org/something

flowchart TD
    A -- Permanent Redirect (301) --> B
    B -. CNAME .-> C
    C -.-> D
    
    A("loopdocs.org/something") 
    B("**www**.loopdocs.org/something")
    C("loopdocs.**github.io**/something")
    D@{ shape: processes, label: "GitHub Servers IPs" }

Loading

Once this configuration has been set up, we will suggest using links with loopdocs.org or www.loopdocs.org (instead of loopdocs.github.io) in FaceBook posts to see if this fixes the issue.
The 3 URL forms will coexist, which means that all existing links (using loopdocs.github.io) in old FB posts will continue to work as before. This is a non-breaking change.

Here we go.
Now, let's answer the "How?" question.

How?

ℹ️ Source: GitHub

Configuring loopdocs.org as a custom sub-domain on GitHub Pages consists in:

• Verifying the custom domain
• Configuring the Custom Domain on GitHub Pages
• Securing the Custom Domain
• Updating mkdocs.yml

Let's explain each step.

Verifying the Custom Domain

ℹ️ Source: GitHub

• (1) Click your profile icon at the top right of the GitHub page

• (2) Click Organizations

  

• (3) Click the Settings button next to the LoopKit organization

  

• (4) Click Pages

• (5) Click the "Add a Domain" button

  

• (6) Enter loopdocs.org

• (7) Click the "Add Domain" button to confirm

  

• Add a TXT record to the loopdocs.org DNS configuration
  Cf. the screenshot below.

  Record Type	Name	Value	TTL
  TXT	_github-pages-challenge-LoopKit	Paste the value copied at step (9)	3600

  

  Use the name and value as shown on the display.
  IMPORTANT: use the copy buttons to prevent typos.

  • (8) hostname: _github-pages-challenge-LoopKit

  • (9) value: copy the given value

  • (11) Wait until your DNS configuration changes. This could take up to 24 hours to propagate. You can use the below command line in a terminal to check:

    dig _github-pages-challenge-LoopKit.loopdocs.org +nostats +nocomments +nocmd TXT

    If you see a line like the one below, then the changes have been propagated.

    _github-pages-challenge-LoopKit.loopdocs.org. 3600 IN TXT "GOBBLEDYGOOK_HERE"
    

  • (12) Click the Verify button once done and the DNS modification has been propagated

Configuring the Custom Domain on GitHub Pages

• Add Arecords to the loopdocs.org DNS configuration
  This will make `loopdocs.org' point to the IP V4 addresses of the GitHub servers.

  Record Type	Name	Value	TTL
  A	@	185.199.108.153	3600
  A	@	185.199.109.153	3600
  A	@	185.199.110.153	3600
  A	@	185.199.111.153	3600

  If your DNS provider does not allow @ use loopdocs.org. instead.
  IMPORTANT: There is a dot (.) at the end.

• Add AAAA DNS records to the loopdocs.org DNS configuration
  This will make `loopdocs.org' point to the IP V6 addresses of the GitHub servers.

  Record Type	Name	Value	TTL
  AAAA	@	2606:50c0:8000::153	3600
  AAAA	@	2606:50c0:8001::153	3600
  AAAA	@	2606:50c0:8002::153	3600
  AAAA	@	2606:50c0:8003::153	3600

  ℹ️ Source: GitHub

• Add a CNAME record to the loopdocs.org DNS configuration
  with the name www and the value LoopKit.github.io..

  Record Type	Name	Value	TTL
  CNAME	www	LoopKit.github.io.	3600

  IMPORTANT: There is a dot (.) at the end of the value.

• Open the loopdocs GitHub repository: https://github.com/LoopKit/loopdocs
  The DNS change above may take one hour to be propagated.

  • Proceed as described in the image below:

    

  • Click Enforce HHTPS

• Create the gh-pages branch on this GitHub repository:

  If it does not exist yet here is how to create it (once) for the GitHub UI to pick it up in the branch chooser 🐓🥚 :-).
  Assuming that in your local loopdocs repository, the:

  • upstream git remote denotes the LoopKit/loopdocs
  • origin git remote denotes your clone of the repository YOUR_USERNAME_HERE/loopdocs
    Use git remote -v to check if this is the case.
    First, make sure to have committed or stashed your current modifications.

  git checkout --orphan gh-pages
  git reset --hard
  git commit --allow-empty -m "fresh and empty gh-pages branch"
  git push upstream gh-pages

Securing the Custom Domain

ℹ️ Source: GitHub

Updating mkdocs.yml

• Set site_url to https://www.loopdocs.org/loopdocs/ in the mkdocs.yml configuration file.

  site_url: https://www.loopdocs.org/loopdocs/

---

EDIT:

• 2025-01-08: Add Updating mkdocs.yml section

[jlucasvt]

When you’re ready please send me an email @getrileylink.org with the (txt) name/value record to add and I’ll also update the A, AAAA and CNAME records as specified.

[ebouchut]

I will get back to you tomorrow once I’m back from the commemoration in Paris.

[ebouchut]

I do not have permission to change the LoopKit GitHub organization.

However, this is required to:

• Verify the custom domain
• set the custom domain in LoopDocs' GitHub Pages
  (see issue description above).

❓Who do I need to ask for help to perform this operation?
cc @ps2 @marionbarker