freenode/web-7.0

The freenode website, home to our blog, knowledge base and policies

web-7.0

A shiny replacement for http://freenode.net.

Building

You'll need our node.js dependencies:

$ sudo npm install -g [email protected] svgo uglify-js
$ npm install

Then, assuming a Python 3.4 (or later) installation:

$ python3 -m venv env
$ . env/bin/activate
$ pip install -r requirements.txt
$ cms7

If everything went well, you should see a lot of log output, and out/ will have the website in it.

Because we generate the site statically, you'll need to re-run cms7 each time you change something. If your editor likes compile commands that can run from any directory, you can also use cms7 -c /path/to/config.yml.

Contributing

• Whenever possible, one commit per feature.
• If feature/pull-request branches have only one developer, please regularly rebase them onto main until they are merged in.
• Don't merge branches with meaningless commit messages; always squash them instead.
• Wait for discussion of big changes. Your branches will still be here tomorrow.

Please comply with the contribution guidelines

Helpful tip for those merging PRs: you can browse the tree a merge would result in by navigating to https://github.com/freenode/web-7.0/tree/pull/XYZ/merge, where XYZ is the pull request number.

You can also go to https://freenode.net/web-7.0/BRANCHNAME/ to see a build of any particular branch. This also works for internal pull requests (they are named pull-X).

Architecture / Orientation

The site is generated from Markdown sources and Jinja2 templates, found in content/ and templates/ respectively. The Travis build deploys to GitHub Pages automatically on every push.

Various modules convert the sources to a useful output structure. Eventually cms7 will document this process, but for now:

• content/pages/ contains plain pages which are rendered in out/ using page.html.

• content/news/ contains blog/news posts which are rendered in out/news/ using article.html.

• content/kb/ contains KB categories: each directory content/kb/X/ has the entries for category X. These are rendered in out/kb/answers/ with kb.html.

  Indexes of these entries are rendered in out/kb/ with kb_index.html, according to a list in config/kb.yml.

Markdown metadata

cms7 uses the markdown metadata extension, and recognises some special keys:

• title sets the page title
• slug overrides the target URL: pages/hello with slug: banana would become out/banana.html
• template overrides the template with which to render this Markdown file

Blog-specific:

• author
• date
• enclosure sets the podcast URL of an article

Internal linking

Everything that ends up in the final output has a name that identifies it to the rest of the website. If a file is derived directly from an input file, generally its name is derived from the name of the input.

• Markdown files like content/pages/hello.md are named their own name relative to the content directory, minus their extension: pages/hello.
• static resources like static/img/cat.jpg are named their own name relative to the repository root: static/img/cat.jpg.
• Templates that are rendered from nothing (e.g. to make the index page) are named whatever the config file says to name them.
• KB indexes are named kb/index/X, where X is the name of the index in config/kb.yml.

cms7 can generate a relative URL to anything with a name from any page. This should always be preferred over manually writing links. To generate a relative link from a Markdown document, just link to a name:

[A page about frogs](pages/frog)

To do the same from a template, call url_for:

<a href="{{ url_for('pages/frog') }}">A page about frogs</a>

web-7.0's Issues

channels: HELP EXTBAN is a little unclear on what to do

• https://freenode.net/kb/answer/channels

If you've not been in the channel in question recently, it's possible that you're affected by a wide-ranging ban, so pay attention to any bans that include * or ? wildcards. Bans that begin with a $ sign are extended ban types; you can see more information about these by sending the HELP EXTBAN command on IRC.

If we assume that the person reading this is IRC NEWBIE, how will they interpret sending the HELP EXTBAN command? I think there are only two ways:

• HELP EXTBAN send to channel or query or whatever they had open.
• /HELP EXTBAN which tries to get help for IRC client command in case of at least WeeChat resulting to No help available, "extban" is not a command or an option.

It should possibly say /QUOTE HELP EXTBAN which should be understood by all clients.

Transfer podcasts

Move old podcast episodes to static/podcast

Search box

In case of information being spread over lots of separate pages: maybe add a search box (header)
(floating left to PIA logo)

(This comment has been heavily edited by the repository owner without my consent and thus no longer necessarily represents my views and opinions)

KB about cloaks

There's an (imo) very unfortunate gist floating around that is linked in #freenode what feels like about a million times a second. I'd obviously rather people just stop linking to it, but that seems unlikely to happen, so I wonder if we should add a page in similar vein—at a minimum, we could make sure it's not full of incorrect information.

See also #135

Site is inaccessible or severely degraded over SSL

Tapping CTRL + F5 changes nothing.

Enable DNSSEC for freenode.net

It happens by enabling DNSSEC with CloudFlare's instructions and adding DS record to Gandi with CloudFlare's instructions.

Related:

• #144 which is also clicking buttons at CloudFlare panel.

Server table

As discussed in irc channel this issue is just to leave as an explanation. There won't be any table of servers as those get outdated quickly and those isn't sustainable to manage. Those only links to irc.freenode.net and chat.freenode.net will be on the site

form compability

https://gist.github.com/svbeon/82d0641399701b021c3e gist with an example implementation

Opening for applying styles to :freenode/gms

Images

All images must be downloaded from old blog and correctly linked in news

Redirect from http to https either not in place or not working

See title, tested with Firefox 45 and chrome 50.

Entering https://www.freenode.net manually works, cache doesn't seem to be in place, can't see anything in the headers that looks like a redirect to https.

Knowledge Base "unfriendly"

The knowledge base requires many clicks to view the information. While this is not a terrible solution, it can get confusing for users since it provides no easy way to find where a solution might be without browsing through Knowledge base and then into subsequent items.

While the "3 click" rule is highly debated, the amount of effort to find information has increased in complexity. For example, on this site, a user now has to depending on their screen, scroll to the bottom of the site every time to view the navigation.

One thought would be to simplify how the information is presented, and modify the navigation to have it fold and be on the top of the site - this way its similar to many other sites providing a more consistent user experience.

Additionally, the present knowledge might look better if the other pages were consistent, some pages use headers to define titles, the knowledge base is much smaller, which seems to flow the viewport differently.

Add some delimiter between tr's

If we look at this table on /support

We note that there is no delimiter between the table rows, I would suggest either borders between them

Or by alternating the row colors with :nth-child([even|odd])

This is to give better readability to the tables

Error 404 handler

A error 404 page schould be created a well, likely there are broken links.

Social icons disproportionally large for small viewports

Enable HSTS for freenode.net

As you use CloudFlare, you could just go to https://www.cloudflare.com/a/crypto/freenode.net#security_header and enable it there.

I don't think there is any reason why browsers should fallback to insecure connection with freenode.net.

UX: Lack of anchors for linking

As discussed on IRC, if multiple pieces of information (e.g. registering a nick, identifying to it and nick expiration) are kept on the same page, for the sake of linking to it (either from project documentation, IRC or whatever else) it would be nice to have anchors.

A different approach would be having separate pages for that kind of information, from an UX point of view I highly discourage that as some information depends on other information or, based on context, can be part of a workflow.

Design: waste of horizontal space

On desktop resolutions, pages which are mostly text (e.g. http://freenode.net/changuide) have a lot of horizontal whitespace.

These days most desktop screens have a wide screen format, thus going for vertical space instead of horizontal space makes less information visible and requires scrolling. Also this requires the visual point of focus to jump a lot while reading, which makes the text more tiresome to read.

Content: Lack of information about nickserv's VACATION

Nickserv's help mentions VACATION (extending the nick expiry time), http://freenode.net/policies doesn't, so whatever of the two is true with new policies should be put into either nickserv help or the policy page

Suggestion: re-linking

As soon as it is clear where content is placed (e.g. sub-pages or one big page, but with anchors):

It would be great if for information that was present on the old page and is still available on the new one (Examples: SASL, Nick registration, On- and Off-Topic, Channel Guidelines, Nick Expiry, Connecting to freenode) some re-linking could be set up.

Reason: lots of projects have these links in their internal documentation (Wiki, written documentation, IRC bots and topics ...) which are now all dead, despite the content still being there.

Redundant identification information

http://freenode.net/kb/answer/registration
Sort of tangential to #139, but step 4 of Nickname Setup is mostly redundant with the Logging In section below, the only difference being the lack of SASL in the former. Should we delete that step since people will most likely keep reading the next section anyways?

"featured group" feature, show on front page

Cloudflare throws incorrect 404

Can we get cloudflare to use the /404 page we have instead of the cloudflare one ( @christeld )

kb answer chat doesn't talk about the domain name at all

• https://freenode.net/kb/answer/chat

It's not mentioned that the SSL certificate is valid only for *.freenode.net. At least on #ZNC we have frequently asked question on why freenode's client is invalid and the answer is more often using chat.freenode.org or other CNAMEd domain than not having ca-certificates installed (which also happens a lot on router OSes which aren't mentioned on that page either).

SASL configuration information lacking

A quite important piece of information, how to connect via SASL, has not been ported from the old website.

This is especially bad because

1. The content was already there and correct
2. Users of some ISPs and VPN providers are required to connect via SASL, thus for these users this is vital information

UX: Feature request: add next/prev etc. links to blog post on the front page

Situation: Right now you have exactly one "blog post" visible on the front page

Problem: if there are multiple currently interesting blog posts, e.g. right now the new website and the April 1st quiz, it's a bit tiresome to flick through the desired information

Solution: add the next (and thus: previous) link on the frontpage as well (it's present in the archive)

Deluxe variant: the white stripe would be almost perfect for flicking through (e..g on mobile) and visually hint that there are more entries on the sides. However, this requires either javascript or lots of css trickery, so probably it's not wanted.

Palette

We're using a lot of slightly different colours:

;; grep -o '#......' static/css/style.css|tr A-Z a-z|sort|uniq
#292f2f
#2fa6bc
#3a4346
#4beb4a
#4c5456
#bdbcbc
#e6e6e6
#ecf7fa

We probably want to do something about that.

Content

There is currently a lack of content, it needs to be added

Feed generator

Broken links in footer.

"Register as a group" & "Existing groups" both lead nowhere.

Old links in news posts

See this paste that contains a grep output of grep -r "shtml" content on branch master, eventually some of those links should be edited

Some pages use incorrect markup for headings

Currently paragraph headings (e.g. "Nickname ownership" on http://freenode.net/policies) are just bolded paragraphs, which results in no vertical spacing. Pages with lots of paragraphs with a heading (e.g. http://freenode.net/policies) appear vertically as one single block of text.

Either add some vertical spacing (more top than bottom), or convert them to html headings.

Really long words/blocks will break viewport

Eventually avoid using word-wrap: break-word; (won't give fancy hyphens tough)

Pre-GMS page about groups?

A possible resolution to #133 - create a page explaining the GMS situation and detailing the interim (projects@) registration process and when it's appropriate to use that.

cc @christeld

UX: Dead links prominently placed

Both on the front page ("register group") and in the footer (also group related things) are dead links. I highly recommend hiding these until the content becomes available.

Footer breakpoints look weird when resizing the window

Design: Font leads to slight horizontal misalignment

The font used leads to slight (1-2 pixel) horizontal misalignment.
This is best seen in titles, e.g.

but also happens in normal paragraphs.

Affected letters seem to be at least N, R and H, which are slightly shifted to the right.

As this seems to be a font issue that can't be fixed easily, maybe consider a different font.

(Sounds like a minor issue, I fully agree, however, it's one of these things that bother you a lot, even without having OCD or the likes. There is something slightly wrong, and you at first can't figure out what)

UX: Most important information is well hidden

One of the most important information for an IRC network is how to connect, thus: server address(es) and port(s). This information is well hidden on the new website, I recommend either placing it on the front page or at least linking it.

#66 broke footer wrapping behaviour

#66 502cdd5

Form styling needed if searchbar and if applying this style to gms

Suggestion (dummycode):

input[type=text] .search:before {
  font-family: "font awesome";
  content: "\f002"; /* .fa .fa-search */
} 
input[type=text] .search {
 padding-left: "width of icon";
} 

Design: Table cells hard to distinguish

Table cells are hard to distinguish from each other, e.g. on http://freenode.net/support depending on your text width (various desktop resolutions tested) the text "Pentium 4 or better dedicated server 64-bit multi-core" appears to be one flow of text, even though it should be separated ("Pentium 4 or better" and " dedicated server 64-bit multi-core" being two different items)

Either spacing or lines between table cells (maybe a somewhat lighter grey) should be used.

Breadcrumbs for a11y

I think it would be good for the website to have some level of breadcrumbs to work out where you are, and to quickly get back to the page you were just on, other than hitting the back button

Cloudflare cache and SRI

Eventually implement an addition to Subresources to be updated by cloudflare by letting cms7 add ?commit to the end of the link, for example:

<link href="static/css/style.css?8e4058c" rel="stylesheet"/>

Also eventually let cms7 calculate the css files SRI hashes and add them, for example:

<link href="static/css/style.css" rel="stylesheet" integrity="sha384-az4KLkHdzQqenZ5ZMjJQPXpywcnHbBuaxVUbO/ZOk5WdI3uslVMOm4lA2b5GhDv9" crossorigin="anonymous"/>

News archive is horribly styled

Seems .copyright has gained +1px height

If you look at .copyright at the CC logo you'll see extra margin below it:

Content: Lack of channel mode help

The old page provided help on cmodes, this has not been ported (yet) to the new page.

This is bad as the official documentation of the ircd (/help cmodes) lacks modes (e.g. +S for SSL only) or important parameters, e.g. the extban syntax, which is both important for +b but also for +I, which had great examples on the old page that are now lacking.

UX: Spacing between links on mobile

On mobile devices with small screens the spacing between the links in the footer is so small that on touch devices, which most of these are, it's hard to click on the correct link.

Blockquotes need styling

Blockquotes

Responsive tables

Wider tables will currently break the display by overflowing the viewport on small screens and the div on large screens, this is because overflow: visible; by default, to make them responsive we would preferably need <table> wrapped inside a <div> with overflow: auto;

Originating from #83

My opinions: don't use line height, add padding above the element instead,
Less padding below last footerchild on mobile, maybe above first child as well, pad the footer content more left please

rebrand FAQ->KB