User reported Issue: Building a static website with Jekyll (on Windows)

[anisa-hawes]

A user has reported that the command choco install ruby -y is not recognised by GitBash on Windows.

They are following the instructions given in the On Windows section of en/lessons/building-static-sites-with-jekyll-github-pages.

I note that the En Windows section of es/lecciones/sitios-estaticos-con-jekyll-y-github-pages does not use the Chocolatey package manager.

[DanielAlvesLABDH]

Hi @anisa-hawes also in the Portuguese translation we had some difficulties on that section and we suggest a different path. The translation will be submitted this moth I think.
Here are the translation of that section if it helps (in Portuguese):

No Windows

As instruções para usuários do Windows diferem das instruções para usuários do Mac, apenas nesta seção “Instalando dependências”. Faça o seguinte se estiver a utilizar o Windows.

Nota de tradução: ao testar a lição, as indicações originais para Windows não funcionaram, pelo que a seguir propomos um procedimento alternativo, no caso de estas instruções não funcionarem no computador Windows do usuário.

1. Precisamos de uma ferramenta de linha de comando que reconheça os mesmos comandos que os computadores Mac e Linux (por exemplo, sistemas operacionais Unix). Visite https://git-scm.com/downloads e clique no link “Windows” em “Downloads”. Assim que o download terminar, clique duas vezes no ficheiro descarregado e siga os passos para instalar o Git Bash (deixe todas as opções como estão).

2. Abra o “Prompt de Comando” (abra o Menu Iniciar e pesquise “Prompt de Comando” e uma aplicação que pode abrir deve aparecer).

Nota de tradução: em determinados casos, se o antivirus estiver ligado, pode aparecer uma mensgem de erro a dizer "acesso negado". Nesse caso, desligue temporariamente o antivírus até concluir estas instruções.

3. Chocolatey é um “gestor de pacotes”: código que lhe permite descarega e instalar, facilmente, software de código aberto no Windows a partir da linha de comando. Agora vamos instalar o Chocolately (certifique-se de copiar todo o grupo de texto em baixo em conjunto, e não como linhas separadas). Introduza o código mostrado nas etapas abaixo (o código é apresentado desta forma), mantendo as dicas de linha de comando acima em mente:

   @powershell -NoProfile -ExecutionPolicy unrestricted -Command "(iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))) >$null 2>&1" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin

Nota de tradução: este passo de instalação pode gerar erro caso tenha um antivírus ativado. Para utilizar o "Prompt de Comando" tem de o "Executar como administrador". Em algumas versões do Windows a PowerShell pode não estar ativada, sendo que é necessário ativá-la para realizar esta lição. Na pesquisa do Windows procure "Ativar e desativar funcionalidades do Windows".

5. Feche a aplicação “Prompt de Comando” e abra “Git Bash” (que instalou recentemente). Agora utilizará o "Git Bash" sempre que a linha de comando for solicitada.

6. Jekyll é construído a partir da linguagem de codificação Ruby. Ruby Gems facilita a configuração do software Ruby (é um gestor de pacotes, assim como o Homebrew, - acrescenta algumas coisas para tornar as instalações Ruby mais simples). Vamos agora instalar o Ruby (isto levará alguns minutos):

   choco install ruby -y

7. Feche o programa de linha de comando e reinicie o computador (o Ruby não funcionará até que o faça)

8. Jekyll é o código que cria o seu website, tornando mais fácil realizar certas tarefas comuns, como a utilização do mesmo modelo (mesmo logotipo, menu, informações do autor ...) em todas as páginas de publicação do seu blog. Há mais informações sobre o que são sites Jekyll e estáticos e sobre porque deseja usar Jekyll para fazer um site estático, acima. Vamos agora instalar o Jekyll (se a Segurança do Windows fornecer um pop-up de aviso, ignore-o):

   gem install jekyll

No Windows (instruções alternativas)

Nota de tradução: estas instruções alternativas para usuários do Windows podem não funcionar para usuários de versões Windows abaixo do 10.

1. Na pesquisa do Windows procure "ativar ou desativar as funcionalidades do Windows". Ative a opção "Subsistema Windows para Linux" (nota: o Windows vai pedir para reniciar o computador).

2. Abrir a "Microsoft Store", procurar e instalar o "Ubuntu 18.04 LTS".

3. Já tem no menu Iniciar a instalação de Ubuntu. A primeira vez que corre este software, na linha de comando é pedido que crie um nome de super utilizador (UNIX username) e uma palavra-passe.

4. Digite o comando seguinte para atualizar as configurações do Ubuntu:
   sudo apt-get update (introduza a sua palavra-passe de super utilizador, caso seja pedido)

5. Digite o seguinte comando para instalar o Ruby (isto pode demorar vários minutos):
   sudo apt-get install ruby-full build-essential zlib1g- dev
   (introduza a sua palavra-passe de super utilizador, caso seja pedido)
   Caso pergunte se quer continuar escolha "yes" ou "y".

6. Digite o seguinte comando para instalar o Jekyll:
   sudo gem install jekyll

[DanielAlvesLABDH]

Look for the several "Nota de tradução:" where we explain why we change several things in this section

[anisa-hawes]

Thank you, @DanielAlvesLABDH. It is extremely helpful. I really appreciate you sharing this.

[anisa-hawes]

Hello @DanielAlvesLABDH,

Thank you so much for these insights!

I've tested your method for these steps to see how they help Windows users move forwards through the lesson. Success! Using the alternative step-by-step you've proposed I have installed Ruby Gems onto Windows 10.

If my (very rough) translation is correct, the first thing your team observed is that Step 3 (the step to install of the Chocolaty package manager, below) generated an error if any antivirus software is enabled.

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "(iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))) >$null 2>&1" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin

You advise that if using "Command Prompt” it is necessary to "Run as administrator". You also note that in some versions of Windows, PowerShell may not be enabled, and that will need to be enabled to complete this lesson (in Windows, search for "Turn Windows features on and off”).

Your proposed alternative steps for Windows users (running Windows 10 and above) are:

1. In Windows search, search for "turn Windows features on or off". Enable the "Windows Subsystem for Linux" option (note: Windows will ask you to restart your computer).
2. Open "Microsoft Store", search for and install "Ubuntu 18.04 LTS".
3. The first time you run this software on the command line you will be asked to create a super user name (UNIX username) and a password.
4. Type the following command to update Ubuntu settings: sudo apt-get update (enter your super user password if prompted)
5. Enter the following command to install Ruby (this may take several minutes): sudo apt-get install ruby-full build-essential zlib1g-dev. Enter your super user password if prompted. When asked if you want to continue, choose "yes" or "y".
6. Enter the following command to install Jekyll: sudo gem install jekyll

--

Hello there @svmelton and @rivaquiroga. Do you agree it would be useful to update the EN and ES versions of this lesson with the Portuguese team's alternative method?

We could also add alert boxes to explain the changes, using the Translator's Notes which Daniel has shared above?

Alert 1: when testing the lesson, the original instructions for Windows did not work, so below we propose an alternative procedure, in case these instructions do not work on the user's Windows computer.

Alert 2: this installation step may generate an error if you have an antivirus enabled. To use "Command Prompt" you have to "Run as administrator". In some versions of Windows, PowerShell may not be enabled, and it is necessary to enable it to complete this lesson. In Windows search search for "Turn Windows features on and off".

Alert 3: These alternate instructions for Windows users may not work for users of Windows versions below 10.

[svmelton]

Thanks @anisa-hawes! Yes, let's update.

[DanielAlvesLABDH]

Dear @anisa-hawes I think you interpreted our Portuguese correctly ;-) Thanks!

[rivaquiroga]

@anisa-hawes, the ES translation is currently using an alternative method that avoids the need of Chocolatey. As far as I know, it is working as expected, so we better keep it as is.

[anisa-hawes]

Hello @rivaquiroga. Yes, I noticed that too.

I note that the En Windows section of es/lecciones/sitios-estaticos-con-jekyll-y-github-pages does not use the Chocolatey package manager.

I'll go ahead and test the method used in the ES lesson. If it works smoothly, perhaps it is best that we update the EN (and forthcoming PT) to use the same method. Do you agree that we should try to keep all three lessons consistent?

[DanielAlvesLABDH]

I agree to keep all versions of the lesson consistent, with the PT option or the ES option

[anisa-hawes]

Thank you, @DanielAlvesLABDH. I'll update you here when I've tested the method used in the ES lesson.

[anisa-hawes]

Okay – I've roughly translated the ES method and have tested these steps. I've successfully installed Ruby Gems and Jekyll onto Windows 10. I did find some parts of these instructions slightly confusing, but this could definitely just be me misunderstanding the Spanish!

--

• I wasn't sure if I should have been working on Git Bash or the Command Prompt app. Is it optional?
• The steps are numbered 1., 2., 1., 1., 1. Could we adjust this numbering to make things clearer?
• I installed Ruby+Devkit 2.7.5-1 (x64) following the advice here which reads: "If you don’t know what version to install and you’re getting started with Ruby, we recommend that you use the Ruby+Devkit 2.7.X (x64) installer".
• It looks like the most recent version is now Ruby+Devkit 3.0.3-1 (x64) (and this is now the third option in the WITH DEVKIT column). Maybe we should adjust this step to make it less specific? Shall we simply advise "download the most recent version"?
• The Command Prompt console didn't automatically open when the download was complete as indicated in the lesson. In fact, unexpectedly, the install seemed to be partly completed by an Install Wizard (a Windows-style dialogue box) and partly in the command line... I was asked both by the Install Wizard and the Command Prompt which components I wanted to install, and both times pressed “Enter” to install everything.
• After pressing Enter the second time in Command Prompt, the console did close automatically.

From the step to verify that the Ruby installation was successful, everything was as described in the lesson.

I re-opened the console and typed: ruby -v

Then, I installed Jekyll, running: gem install jekyll

I waited until installation was complete and I saw the confirmation message 26 gems installed

Finally, I checked that Jekyll had been installed correctly. I typed: jekyll -v

and received the success confirmation that the latest version of Jekyll (now 4.2.1) was installed successfully.

---

I'm not certain what the particular benefits of either this or the PT method would be? But I welcome your thoughts, @rivaquiroga, @DanielAlvesLABDH and @svmelton.

One possible benefit to consider, is that this ES method doesn't use sudo. Would you generally try to avoid this?

If we do decide to go with this ES method, I'd be grateful for a conversation with someone to clarify the steps and discuss the questions I've outlined above.

[anisa-hawes]

Hello all,

Apologies for the delay in following up here. I'm uncertain how to move forwards. It seems we have a couple of options, and a few things to consider:

• I can prepare an update of the EN lesson using the instructions the PT team have devised in the process of their translation. I've tested these steps on Windows 10. I found the method worked well and the notes were helpful – I think these could be formatted as alert/information boxes in the lesson.
• If we opt to do this (update the EN lesson using the method suggested by PT editors and translators) would we also want to update ES?

Alternatively,

• I can work with the ES team to clarify the steps of the method outlined in their translation, and prepare an update to EN based on these. A few questions and points of confusion came up when I was testing these steps, which I have outlined above. Following that, the PT could revise their forthcoming translation.

Do we want to keep the methods taught in all three lessons consistent? My sense is that this is preferred where it is possible, and @DanielAlvesLABDH has expressed agreement but I welcome you thoughts @rivaquiroga and @svmelton.

[spapastamkou]

Not sure if this is the lesson @InesSalome is editing currently but I tag her here to see with you, Anisa

[anisa-hawes]

Thank you for making this link, @spapastamkou! I didn't realise that an FR translation was also in progress! I see it now, #449 I can update Gwenaëlle @InesSalome with any revisions agreed here.

[rivaquiroga]

@anisa-hawes, I'm pinging @hdcaicyt, who translated the lesson and proposed the installing method that is used in the Spanish version, in case you have any question.

[hawc2]

@anisa-hawes can I help you with closing this issue? I can help wrap up the changes in English and we can go from there?

When we meet to discuss improving translation guidelines and workflows for the English team in a couple weeks, maybe we can tackle this ticket around the same time?

[anisa-hawes]

Hello @hawc2. Good to speak with you today. It would be great if you could help me to test this 🙂

As I mentioned, a reader got in touch last week (#2837) who had encountered the same problem at the choco install ruby -y step. They explained that they had been able to move forwards by following these instructions which are specific to Jekyll on Windows.

(When working on this previously, I had access to a friend's computer (running Windows 10) but I don't any longer).

[hawc2]

@anisa-hawes this all sounds like a good solution to me. Do you need my assistance with anything? It sounds like we're going to update the lesson in all languages with some version of these updated instructions linked or included, right?

[hawc2]

@anisa-hawes can you clarify for me what is holding up this bug fix? I'm sorry if I'm missing something, but it sounds like the solution to the bug is provided by the attached guidelines, so can't we just replace preexisting guidelines with that link and call it a day?

For installation instructions, it makes sense to link to the software's own documentation since they'll be updated pretty regularly.

[anisa-hawes]

Dear @hawc2.

Thank you for checking in. Apologies for the delay.

The guidelines to be updated are effectively the whole of the sub-section tilted On Windows. I don't think we would simply want to replace that section with a single link.

Above, I tested the steps as written in the Portuguese translation and the Spanish translation. Both work.

I posed a question above, about what the particular benefits of either method would be?

I think it is best you take the decision about which course to take:

• translate the Spanish (code + the commentary) into English, or
• write a new sub-section that avoids choco and uses roughly this method instead

I can ask the author about this, as I am in touch with them about another Issue. If you agree, I think we could allocate one our 'lesson maintenance' budget units to this.

[hawc2]

I would go with 2) the documentation provided by Jekyll. If that means not using Choco, that's probably for a good reason. If some of the instructions or lines of code need to be reproduced in the lesson's bullet points, I think that's fine, but you can still keep it minimal and otherwise link to that source for up to date install instructions. Sounds good about reaching out to the author! If they can review and make these changes as they prefer, that would be great

[anisa-hawes]

Thank you, @hawc2. I will put it on my list to contact the author next week.

[anisa-hawes]

Note:

I have written to the author to ask if they have interest (and time) to help us with this update.

[charlottejmc]

I'm reopening this issue because I merged the PR before receiving @jenniferisasi's translations into Spanish. Sorry!

@jenniferisasi, I've restored the branch called Issue-2462, where you can make your edits to sitios-estaticos-con-jekyll-y-github-pages.md. We'll simply have to generate a new pull request from this branch once you're able to translate the changes on your side.

I'm sorry this makes things a little bit more complicated to navigate, but please do still refer to the initial commit I made in the original branch to check the changes in English.

Thank you again for your time and support with this.