[START HERE!] Outreachy #1: Set up a development environment with the UNICEF Inventory example site

[jwflory]

Welcome to Outreachy 2022 with @unicef! This is an issue meant for newcomers working on the UNICEF Inventory project. Before working on this project, you should read the full project profile from the Outreachy website for more background. It will make your first contribution and efforts here easier!

Summary

Set up your development environment with Hugo and the UNICEF Inventory theme's example site.

Background

When you are working on the UNICEF Inventory theme, you will need to test and verify your changes as you work on the theme. The easiest way to do that is to run Hugo on the example site included in this repository. You will be able to test your changes out and see them in real-time before submitting a Pull Request for review.

The purpose of this issue is a milestone in your Outreachy application to @unicef. To complete this issue, your mission is to set up your development environment and share proof of that by uploading a screenshot to this GitHub Issue. Once you have done so, you will be "assigned" to this GitHub Issue as verification you have completed the requirement. You can also provide help and guidance to others who ask for help in this issue if you wish.

This issue will remain open for the full contribution period of this Outreachy round and will close on 22 April (end of contribution period).

Details

To complete this issue, do the following:

1. Install Hugo (see docs). Hint: The best way to go is to use a precompiled binary with a more recent version of Hugo.
2. Clone this git repository to your machine.
3. Edit the example site config.yml to change the site title to your GitHub username and change the params.primary_color to your favorite color.
4. Run hugo serve in the terminal and open the example site to see your changes.
5. Take a screenshot of the local site preview from your browser.
6. Upload the screenshot to this GitHub Issue.

Hint: The contributing guidelines have extra help if you get stuck. #TODO Write contributing guidelines for the Inventory theme.

Outcome

• You successfully installed Hugo, made changes to the example site, and saw them live from a local preview on your machine.
• You are now ready to move on to the next Outreachy applicant issue, #60.

[Yavnikaa]

I have done as directed on my local machine. Hope this is correct! :))

[steph237]

I cloned the repo and followed the instructions. I hope I did it right .

[BeeBombshell]

Hi @jwflory... I have set up the development environment and made the changes mentioned. Kindly take a look... 😄

[jwflory]

Thanks @Yavnikaa, @steph237, & @BeeBombshell, looking good! 👍🏻

[zaa6]

My submission

[Neha9849]

Here is mine

[roli25]

Hello @jwflory I have followed the instructions. Kindly have a look.

[jwflory]

@mmldco @Neha9849 @roli25 All looks right, thanks for following up here!

[gnikita432]

Hii @jwflory I have cloned the repository and set it up in my local environment and made the changes mentioned.

Thank you!

[jwflory]

@gnikita432 Looks good! 👍🏻

[AbihaFatima]

Hey @jwflory @Idadelveloper, I made the required changes as per the instructions mentioned above. Please take a look! Thanks

[Biki-das]

hey could anyone guide me a little bit, i am stuck with some error , when i try to run the site i get a config error, could anyone help me with the steps they followed to setup the project?

[Idadelveloper]

Since the config.yml file is missing you can create a new file at the repo's root and call it config.yml. Copy and paste this and make the necessary edits.

---
###############################################################################
#                                                                             #
#                            WEBSITE CONFIGURATION                            #
#                                                                             #
###############################################################################

# --- base website settings ---

baseURL: inventory-hugo-theme
title: your-user-name
languageCode: en-us
enableEmoji: true
enableGitInfo: true

# Optional: Add Google Analytics tracking support.
googleAnalytics: ""

# --- markup settings ---

markup:
  asciidocExt:
    preserveTOC: true
    sectionNumbers: true
  goldmark:
    renderer:
      unsafe: true
  highlight:
    anchorLineNos: false
    codeFences: true
    guessSyntax: false
    hl_Lines: ""
    lineAnchors: ""
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    style: murphy
    tabWidth: 4

# --- privacy settings ---

privacy:
  googleAnalytics:
    anonymizeIP: true
    respectDoNotTrack: true
  twitter:
    enableDNT: true
  vimeo:
    enableDNT: true
  youtube:
    privacyEnhanced: true

# --- navigation menu ---

menu:
  main:
    - name: FAQ
      weight: 10
      url: faq

    - name: pages
      weight: 20
      url: pages
      hasChildren: true

    # Sub-pages in this drop-down should correspond to categories created in /content/
    - name: Topic 1
      parent: pages
      weight: 10
      url: topic-1

    - name: Topic 2
      parent: pages
      weight: 20
      url: topic-2

    - name: Topic 3
      parent: pages
      weight: 30
      url: topic-3

    - name: Topic 4
      parent: pages
      weight: 40
      url: topic-4

    - name: Topic 5
      parent: pages
      weight: 50
      url: topic-5

# --- custom settings ---

params:
  logo: "images/logo.png"

  # OpenGraph data
  description: Template site using the UNICEF Inventory theme. This is from the sample configuration.
  author: Our Community of Authors
  image: "images/opengraph.png"

  # customize color
  primary_color: "#4D77FF"
  body_color: "#D8D1C9"
  text_color: "#777779"
  text_color_dark: "#374EA2"
  text_title_color: "#ffffff"
  white_color: "#ffffff"
  light_color: "#f8f9fa"

  # font family (choose from https://fonts.google.com/)
  font_family: "Open+Sans"

  # contact form action (works with https://formspree.io)
  contact_form_action: "#"

  # related article number limit
  article_count: 3

  # brand and identity information
  brand:
    parent_org_name: Example Site
    parent_org_url: https://example.com/
    parent_org_url_legal: https://example.com/privacy/
  footer:
    mainSite: https://unicef-if.discourse.group/c/projects/5
    mainSiteName: UNICEF Innovation Fund projects
    description: Template site using the UNICEF Inventory theme. This is from the sample configuration.

# --- social platform settings ---
# themify icon pack : https://themify.me/themify-icons

  social:
    - icon: ti-github
      name: Theme repository on GitHub
      link: https://github.com/unicef/inventory-hugo-theme
    - icon: ti-twitter
      name: "@GoHugoIO on Twitter"
      link: https://twitter.com/GoHugoIO

# --- taxonomy settings ---
taxonomies:
  alert: alerts
  category: categories
  downloadable: downloadBtn

# --- multilingual settings ---

Languages:
############################# English #############################
  en:
    languageName: en
    languageCode: en-us
    weight: 1
    home: Home
    copyright: Creative Commons BY-SA 4.0. Site theme adapted from UNICEF Inventory theme.
    params:
      banner:
        title: Example Knowledgebase
        subtitle: Template site using the UNICEF Inventory theme. This is from the sample configuration.
        bg_image: images/banner.jpg
        placeholder: Have a question? Search the site here.
############################# Español / Spanish #############################
  # es:
  #   languageName: es
  #   languageCode: es-mx
  #   weight: 2
  #   home: Página principal
  #   copyright: Creative Commons BY-SA 4.0.
  #   params:
  #     banner:
  #       title: "Inventario de Open Source de UNICEF"
  #       subtitle: "Una base de conocimientos de innovación mundial del UNICEF sobre mejores prácticas y recursos para trabajar y dirigir Open."
  #       bg_image: images/banner.jpg
  #       placeholder: ¿Tienes una pregunta? Busque en el sitio aquí.

[reeshipaul]

[Biki-das]

hello @Idadelveloper i have followed your instruction as you said but my image assests are not loading

[Hydriah]

hello @Idadelveloper @jwflory i just completed my setup [

[bl-aire]

hello @Idadelveloper i have followed your instruction as you said but my image assests are not loading

Hello,

I have the same problem while setting up mine. My first guess was that the images weren't referenced properly but every attempt to fix it has failed so far

[anu-phoenix]

Hi! I followed the instructions and this is the output. Please have a look! I hope its correct :)

[chaitri19]

Hello, I followed the instructions and below is my output. Please give me a feedback if something is wrong.

[bl-aire]

Hello @jwflory, I was able to solve the problem I had earlier. This is the result.

[kbetty]

Hello @jwflory while doing my first challenge in the world of open source development have got an error and am a bit stuck. What have done:

I have followed keenly the instruction in the issue above.

And after making the suggested changes, navigated into the my local repo using cd command and run the command hugo serve and I get this error.

opensource@opensource:~/Documents/Outreachy/inventory-hugo-theme$ hugo serve
Error: Unable to locate config file or config directory. Perhaps you need to create a new site.
       Run `hugo help new` for details.

opensource@opensource:~/Documents/Outreachy/inventory-hugo-theme$ 

Is there something have missed out resulting into this error?

[chaitri19]

I was getting same error but then it was resolved using hugo server --theme ../../

On Sun, 27 Mar 2022, 19:36 Betty Mirembe, @.***> wrote:

Hello @jwflory https://github.com/jwflory while doing my first challenge in the world of open source development got an error and am a bit stuck. What have done:

I have followed keenly the instruction in the issue above https://github.com/unicef/inventory-hugo-theme/issues/59#issue-1165503576 .

And after making the suggested changes, navigated into the my local repo using cd command and run the command hugo serve and I get this error.

@.:~/Documents/Outreachy/inventory-hugo-theme$ hugo serve Error: Unable to locate config file or config directory. Perhaps you need to create a new site. Run hugo help new for details. @.:~/Documents/Outreachy/inventory-hugo-theme$

Is there something have missed out resulting into this error?

— Reply to this email directly, view it on GitHub https://github.com/unicef/inventory-hugo-theme/issues/59#issuecomment-1079939006, or unsubscribe https://github.com/notifications/unsubscribe-auth/AUKTEI7V4AGEZQMAKAEI4V3VCBTOXANCNFSM5QNIW3HQ . You are receiving this because you commented.Message ID: @.***>

[Abbiefied]

Hello @jwflory , I just completed the first issue.

[kbetty]

When I use hugo server --theme ../../ I get this error

 Error: add site dependencies: load resources: loading translations: "/home/opensource/Documents/Outreachy/inventory-hugo-theme/i18n/en.yaml:1:1": failed to load translations: unable to parse translation #0 because missing "id" key
map[footer:map[legal:Find legal information and policies related to {{ $.Site.Params.brand.parent_org_name }}'s digital communications.]]

[siddharth628]

Hi @jwflory, It's done.

[sidd-oo]

Hey @jwflory @Idadelveloper, I have been successful in changing the title and the background colour but my screenshot looks a bit different from others. Can you guide me on what I am doing wrong and how can I fix it?

[anu-phoenix]

Hey @jwflory @Idadelveloper, I have been successful in changing the title and the background colour but my screenshot looks a bit different from others. Can you guide me on what I am doing wrong and how can I fix it?

Hello! I was having the same error u can resolve this by running hugo server --theme ../../ in original repo after cd exampleSite

[sidd-oo]

Thank you for offering me help @anu-phoenix I tried hugo server --theme ../../ inside the exampleSite directory but this time I am getting 404 page not found error on live preview. What I am doing wrong here, any idea?

[anu-phoenix]

Thank you for offering me help @anu-phoenix I tried hugo server --theme ../../ inside the exampleSite directory but this time I am getting 404 page not found error on live preview. What I am doing wrong here, any idea?

Use link http://localhost:1313/inventory-hugo-theme/

[bl-aire]

Thank you for offering me help @anu-phoenix I tried hugo server --theme ../../ inside the exampleSite directory but this time I am getting 404 page not found error on live preview. What I am doing wrong here, any idea?

I had similar issues. Entering the url I marked in my browser instead of localhost:1313 fixed it.

[paydendyer]

Hi I have cloned the repository and set it up in my local environment and followed the instructions to make changes.

[RuthAtem]

Hi Everyone. Glad to be here and contribute. Successfully set up and made changes for Step One .

[yokwejuste]

Hey here! happy to contribute here! successfully set up enviornment.

[kbetty]

Finally the development set up is up and running after landing into different errors

@jwflory @Idadelveloper here is my finding why the server may fail to start. I noticed that the two files located at https://github.com/unicef/inventory-hugo-theme/tree/main/i18n fails to load translations hence unabling to parse translation and results into missing the "id" key.

I am not sure whether this happens on all Debian based system(I am using Ubuntu) but what have done to make the server start is to delete those two files en.yaml and fr.yaml. Then the server was able to start successfully.

Am wondering whether this could be a bug that need to be fixed!

[Biki-das]

Hello everyone who is new to UNICEF project, you might have faced some difficulty which i also did, and i figured out a smooth way to set up the dev environment,

First of all in the exampleSite, delete the i18n folder as it is causing some issue, then cd example site, type hugo server --theme .. // .. //

now if you open localhost:1313 you will get a 404 error page, now you need to configure your url and replace it with localhost:1313/inventory-hugo-theme/

[Biki-das]

@jwflory setup done :-)

[Lukong123]

@jwflory @Idadelveloper here's my screenshot.

[Idadelveloper]

hello @Idadelveloper i have followed your instruction as you said but my image assests are not loading

Hello,

I have the same problem while setting up mine. My first guess was that the images weren't referenced properly but every attempt to fix it has failed so far

cd into the exampleSite directory, make the necessary edits in confid.yml and run hugo serve

[JessWillCode]

All Finished!

[ElHombreMorado8]

I made it work using hugo server --theme ../../ from exampleSite folder

[sidd-oo]

I have fun working on this, Kindly Check @jwflory @Idadelveloper

[EmmanuelOloke]

Hugo installed and the server is running without issues. @jwflory @Idadelveloper

[barchakuz]

Hello @jwflory @Idadelveloper , I just completed setup.

[jwflory]

@AbihaFatima @reeshi-18 @Abbiefied @siddharth628 @paydendyer @RuthAtem @yokwejuste @kbetty @Biki-das @Lukong123 @JessWillCode @ElHombreMorado8 @sidd-oo @EmmanuelOloke @barcha47

Thanks all, you are good to go here 👍🏻 I'm not sure if there is a limit to the number of assignees to a GitHub Issue, but I'll try here and see how many folks I can add. If you have not already, please proceed to work on the next issue.

Special thanks for all folks who contributed by answering questions and helping others 💪🏻

[jwflory]

GitHub caps assignees per issue at ten people. We'll use comments to track completion. All three onboarding activities are something to document in your final application for Outreachy.org.

As a follow-up to many questions in this issue, the best way to run the example theme site is to change directories to exampleSite/ in the project, and then run hugo serve. Doing it this way should avoid issues with images and other assets not loading correctly, which is why some screenshots looked different than others (e.g. whether there was a background picture or not). This works because there is a symbolic link that tells Hugo to look in the main repo for the theme, while running the example site from inside the same repository.

[ragini-gp]

@Idadelveloper @jwflory I tried it, but I am not sure whether Home page was supposed to be added or not. Please let me know if any improvement needs to be done. Thanks in advance!

[jwflory]

@ragini-gp Looks good, you can proceed to #60 👍🏻

[manasvvi1]

Hey @jwflory @Idadelveloper, I tried completing the Outreachy#1 issue. Please let me know if any changes are required. Thank you!

[sakshi-0206]

Hey! @jwflory @Idadelveloper I made the required changes. Kindly have a look.

[jwflory]

@manasvvi1 @sakshi-0206 Thanks both! This looks good 👍🏻

I would also like to note that I closed the project for new applicants in the Outreachy portal. It is a very competitive round and we only have one funded internship. It may be strategic to look at other communities with fewer applicants for their mentored projects. I know the Fedora Project is one other excellent community and they are funding three interns.