adambard/learnxinyminutes-site

LearnXInYMinutes.com

This is the Middleman site behind the magic.

To build the site, first install Git and Ruby 3+, then

git clone https://github.com/adambard/learnxinyminutes-site.git
cd learnxinyminutes-site
git clone https://github.com/adambard/learnxinyminutes-docs.git source/docs

gem install bundler
bundle install
bundle exec middleman serve

You need to check out the learnxinyminutes-docs repo as source/docs. All the code that builds the site is in config.rb

learnxinyminutes-site's Issues

Enhancement. Use github syntax highlight.

Enhancement. Use github library "linguist" for syntax highlight.
Github renders ok powershell/en page, but https://learnxinyminutes.com/docs/powershell/ don't. Example where github does ok:

echo @"
This is a Here-String
$aString
"@
# Note that ' (single quote) won't expand the variables!
# Here-Strings also work with single quote

Some pages wrap before 80 columns width on site, but not when I generate the site myself

I have seen this in the [perl6] doc I have been working on. If I generate the site locally then the width shows fine in both Firefox and Chrome. On learnxinyminutes.com though the text is larger and the lines don't fit properly.

Other people have also seen on their pages as well for example the [red] one. It seems to effect all the pages.
Please see: adambard/learnxinyminutes-docs#2303

width enhancement

sometimes text gets out div
objc/en

java/en

etc.

i don't like this
I propose to increase the width of the div.container up to 1000 (for example)

what do you think about this?

Site not being updated...

As stated here: learnxinyminutes-docs

please add instructions for building the site locally

I don't know how to use this repo and I couldn't figure it out after 10 minutes of prodding around so I gave up on making my change.

Change format of docs to the actual language + pseudo-Docco markdown blocks

So, currently the docs are written in a Markdown file, 95% of which are just a giant GfM code block with a header and footer.

The problem with this is twofold:

1. Most editors (well, Vim and Sublime Text 3, at least) won't syntax highlight inside code blocks properly. This means we have to set the syntax for the whole file to whatever it is we're writing, do weird things to the document so that the introduction doesn't throw off the highlighter too much, and undo those weird things again before each commit.
2. Actually running the code we're writing is a lot more difficult than if it was, say, just a .sql file.

What would be better, IMO, is if we could do something like this:

-- <frontmatter>
-- language: sql
-- et_cetera: et_cetera
-- </frontmatter>
-- <markdown>
-- This bit is parsed as markdown.
-- ## This is a H2
-- [this is a link](https://google.com)
-- </markdown>

-- the rest of this document is put in as a code block
SELECT * FROM myTable;
-- until we get to another markdown block
SELECT col1, col2 FROM myTable;

-- <markdown>
-- this ends the previous code block
-- </markdown>

I have some idea how this could be implemented, but I don't know much Ruby or much about Middleman.

Unreadable text on selection

learnxinyminutes-site/source/css/dark.css.scss

Line 1 in 15d8e77

// Implements dark mode feature -- just add .dark to body!

Solution will be just to add one more rule to change color on selection

html.dark {
    ::selection {
        color: #000;
    }
}

Link to the edit page for the appropriate language & lang in the footer

Currently, there is some text asking for pull requests. It could be made to link to https://github.com/adambard/learnxinyminutes-docs/edit/master/<lang>/<language>.html.markdown.

404 when accessing EDN's tutorial

I am getting a 404 error when I try to access the EDN tutorial on the website.

Website down?

Is the learnxinyminutes.com site down? Neither http nor https work. Connection refused.

learncpp.cpp file is in Italian

From the English C++ page, the link to learncpp.cpp leads to an Italian version of the file:

http://learnxinyminutes.com/docs/files/learncpp.cpp

How about anchor navigation in code ?

I suggest something like:

$(function() {

    if (location.hash.indexOf('code-') == 0) {
        $(document).scrollTop($(location.hash).offset().top);
    }

    $(".highlight > span").each(function(i) { 
        this.id = "code-"+i; 
    }).click(function() { 
        location.hash = this.id;
    });
});

I don't know what i doing

i18n issue

I found the values of Select theme are not properly synced with the source data.

This is not correct:

but the entry in https://github.com/adambard/learnxinyminutes-site/blob/master/data/i18n.yaml is correct

Besides, I cannot see how many people modified the files. For example the yaml tutorial. It says "updated by 0 contributors":

This two issues exist both in zh-cn and zh-tw. I don't know others.

Code is less than 80 chars wide

The content area's width of 840px is not sufficiently wide to accommodate 80 characters per line when using Chrome on a completely fresh install of Linux Mint 17.3. Specifically, only 70 characters are displayed per line using this setup.

The same effect is also observed using Chromium, and on Kubuntu 15.10. The issue is thus likely seen in other Chromium-based browsers and on other Ubuntu-based distros as well.

The problem seems to arise due to a slightly larger letter spacing when using the aforementioned combinations, perhaps due to differences in the underlying font rendering engines.

The simplest solution would be to increase the width of the content container (to approximately 950px). Another alternative could be to reduce the letter spacing in the code section (by approximately 0.013em). However, both of these solutions would also affect other platforms where this issue isn't present, perhaps making it somewhat less straight-forward depending on the project's priorities.

Fails to build with Ruby3.0. | Lock to Ruby2.7

# Gemfile
ruby "~>2.7"
...
gem 'nokogiri', '~> 1.11.2'
...

Why not to use Jekyll? I'm trying to build the learnxinyminutes-site by using Ruby3.0 and it fails due to differences in standard lib that is used by middleman deps.

Expected

• Effortless & fast build

Actual behavior

• A lot of incompatibility errors
• Wasted over 2 hours to just to figure out that I have to downgrade ruby & bundler and install all deps

Steps to reproduce

1. Run Debian/[K]Ubuntu 22.04.2
2. Install Ruby3.0
3. Follow instructions at learnxinyminutes/CONTRIBUTING.markdown
4. Fails to build website

Additional information

• Ruby version: 3.0
• Middleman version: 3.3
• OS version: [K]Ubuntu 22.04.2 LTS

Workaround

On Linux/Ubuntu systems with fresh updates you have to install ruby2.7 anyway:

sudo apt install ruby2.7 ruby2.7-dev

Update your Gemfile. Update nokogiri. See related PR nokogiri#2106

# Gemfile
source 'http://rubygems.org'

ruby "~>2.7"

gem "rouge"
gem "pygments.rb"
gem "middleman", "~>3.4.0"
gem "middleman-syntax", "~>3.3.0"
gem "redcarpet", "2.3.0"

gem "haml", "~>4.0.5"

# For feed.xml.builder
gem "builder", "~> 3.0.0"

# Github security recommendations
gem 'yajl-ruby', '~> 1.3.1'
gem 'nokogiri', '~> 1.11.2' 

In your shell, run:

  sudo gem2.7 install  bundler -v '1.17.3'
  sudo bundle2.7 install
  bundle2.7 exec middleman

Note: The last command may leak memory somehow.

Google Chrome (Mac v62.0.3202.62) incorrectly attempts to translate index page

Website not updating

The online website has not been updated since the end of May (?) with respect to changes in the learnxinyminutes-docs repository. Is this normal?

Some pages are not generating because a problem with middleman-syntax/extension.rb

Update: Pull request has been made which uses newer middleman and rogue which solves the problem so editing the file below isn't needed.

---

This line (Line 40) in ~/.gem/ruby/2.3.0/gems/middleman-syntax-1.2.1/lib/middleman-syntax/extension.rb

lexer = Rouge::Lexer.find_fancy(language, code) || Rouge::Lexers::Text

Needs to change to be this:
lexer = Rouge::Lexer.find_fancy(language, code) || Rouge::Lexers::PlainText

---

Doing that the pages generate properly. Some of them are showing up right now but that may not mean they're actually generating properly.

Here is a list. The ones with Missing by them don't show up on the website. The ones without it don't build on my computer, so they may just be using previously built versions:

build/docs/objective-c/index.html
build/docs/ru-ru/objective-c-ru/index.html
build/docs/id-id/pyqt-id/index.html Missing
build/docs/id-id/coffeescript-id/index.html Missing
build/docs/pyqt/index.html Missing
build/docs/rst/index.html Missing
build/docs/sk-sk/elixir/index.html Missing
build/docs/tr-tr/objective-c-tr/index.html
build/docs/kotlin/index.html
build/docs/vi-vn/objective-c-vi/index.html
build/docs/fa-ir/css-fa/index.html Missing
build/docs/fr-fr/objective-c-fr/index.html

I don't really know ruby, I tried to fix it through changing the site's config.rb but just encountered the same issues (or tried updating some of the gems to later version than in the gemfile). Patching that line in middleman-syntax works and all of the generate. The site is locked to older versions of a lot of things, and updating middleman made the clementine extension not work since it's now an old extension method and isn't supported anymore on the latest middleman. @adambard your thoughts?

Moved here from adambard/learnxinyminutes-docs#2513

Two xml links on home page.

Two xml links on home page. The one for Italian has a wrongly named link 'id-id' instead of 'it-it' and in placed in the left column instead of right. I can't find the source to fix. Is there another repository? Is it no longer open source, the site?

Add Opengraph/Schema.org headers

Adding more metadata to the head, especially ogp.me or schema.org fields would add previews to shared links on many platforms. This results in significantly more visible links on social media platforms and increases traffic at almost no cost,

Enhancement Request: Line Numbers

It would be probably meaningful to add line numbers to be able to reference different sections of the code examples. Proposed by @kiru.

'Get the code' links to code in wrong languages

I'm looking at the english versions. C++ is in Spanish, Python 3 in Czech, Bash in Italian and JSON in Lithuanian. Some others like Go and CoffeeScript are fine.

[cue/en] Link to cue docs not working

Description
The link from the homepage to the page about cue doesn't work.

Reproduce

1. Go to the website
2. Scroll down until you see "cue"
3. Click the link
4. See 404 page

Device
OS: ChromeOS
Browser: Chrome

Expected
I expected the page about Cue to show up. It's in the learnxinyminutes-docs repo, but the link seems to fail.

More info

I created a similar issue (#112) a couple of days ago. I wonder if something's wrong in deployment? It could be a kind of whack-a-mole situation, where push one temp fix causes another bug.
Sorry, I don't code in Ruby so I can't help :(

[SUGGESTION] Show translators on document page

It would be nice to show the people who translated a document on the document page.
A lot of documents use the "translators" header but only "contributors" is shown.

If i knew the syntax of the templates a bit better I would have made an pull request.

The site's markdown rendering is significantly different from github's.

The problem

I was about to make a contribution to a page when I noticed that what I thought was a typo was actually a disparity in the way leanxinyminutes and github handle markdown.

Screenshots

learnxinyminutes:

github:

learnxinyminutes:

github:

Possible fix

I'm not a ruby programmer, but from what I dug up it might be a good idea to switch from Middleman's default RedCarpet, to something that implements github flavored markdown.

This way, both contributors and auditors could rely on/count with github's md preview, instead of cloning the site/building the site every time.

Other relevant links:

• https://about.gitlab.com/blog/2019/06/13/how-we-migrated-our-markdown-processing-to-commonmark/
• https://gitlab.com/digitalmoksha/diff_redcarpet_cmark
• https://github.com/github/cmark-gfm
• https://babelmark.github.io/

Update pygments

Can you please update pygments package? Modern version brings much more languages!

Certificate expired on learnxinyminutes.com

Ukrainian language

Hi @adambard,

I'm still confused about the Ukrainian language in the docs repository.

We have:

1. Folder name uk-ua which seems correct to me;
2. All the files have the -ua suffix (c-ua.html.markdown). Shouldn't it be then c-uk instead?
   I'm not proficient in those things and don't know how the parsers/file processors deal with language codes.

Any ideas would be highly appreciated. Thanks!

Enhancement suggestion: user-supplied syntax highlighting rules/logic

Just found this project, it's cool.

There seems to be a small but steady flow of bug reports regarding highlighting issues.

I'm not quite able to tell how redcarpet and Pygments split the task of syntax highlighting, but they/it seem(s) more suited toward well-established languages with clearly-disseminated ideas of what bits should be what color. This particular site has attracted a small proportion of obscurer, more experimental languages.

IMHO, this is a good problem to have :) - some might dismiss the the fringe programming scene as a waste of time and its byproducts as junk, but since a purely academic approach already hit the 99% mark 61 years ago with Lisp, it seems like experimentation is how we'll unearth the practical and useful parts of the other 99%. So, supporting and encouraging everything is going to waste an unknown quantity of time, but it's very important.

With this in mind, a potentially interesting, scalable solution to supporting new and as-yet unknown fringe languages could be to allow the community to contribute its own syntax highlighting functionality that would be run by the server when code written in a given language is updated on GitHub.

The reason I suggest the idea of a generic code sandbox is that such systems are generally set up/shouted at just the once, and then generally remain rock solid; the basic techniques are battle-tested; and there is much discussion of implementation thanks to the profusion of online code evaluation platforms of all kinds, which must deal with all manner of attacks.

I can see such a system potentially encouraging language designers to do real-world headscratching and try and figure out how to make their new language syntax highlight itself. :D

Naturally, contributors would be encouraged to test their implementations on their own systems before uploading the final product to "production", which would then be able to simply apply changes immediately, creating a good feedback loop where further bugs in the fixes would be quickly reported.

I did a little digging; I can't figure if you're on DigitalOcean (your IP address is apparently using DO for its ISP) or Linode (an MX query points to some Linode mail servers), but apparently DO enabled nested KVM literally less than one month ago (!) (see very last post) for their NYC regions, so that could be one possible idea.

I'm imagining something based on the likes of Alpine Linux, since its base images are so small. (You could probably replace its kernel image with a much smaller one though - the kernels I build for KVM are around 1MB). You might start QEMU your own -kernel and a user-supplied -initrd with perhaps the input file attached to -hda and a 1MB empty -hdb available to the code to echo the syntax-highlighted output to. (Pass in a file via -hda, you can cat /dev/sda to read it.)

I love this specific kind of intricate castle-building :) - feel free to lift various parts, or disregard completely.

Many thanks for setting this site up, and coordinating the process of keeping it updated via GitHub.

Dark mode: text hidden on selected elements

The es-es locale text is hidden, but it should be black. This happens when you mouse over as well.

Certificate expired on December 25

Migrated from adambard/learnxinyminutes-docs#3433

@jimpallomeni in adambard/learnxinyminutes-docs#3433 reports:

Please renew your Let's Encrypt certificate for the site.

[ballerina/en] Link to page not working

Description
The link from the homepage to the page about ballerina doesn't work.

Reproduce

1. Go to the website
2. Scroll down until you see "Ballerina"
3. Click the link
4. See 404 page

Device
OS: ChromeOS
Browser: Chrome

Expected
I expected the page about Ballerina to show up. It's in the learnxinyminutes-docs repo, but the link seems to fail.