Improved developer Getting Started documentation (#3)

* improved README.md getting started documentation + github issues config

* fix: miss aligned build in makefile ascii art

* changed parameters in default config for the website

* fix: documentation typo

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 💬 Discord
+    url: https://discord.gg/mF3na6DY # TODO @dvcorreia: this is not a permanent community link
+    about: Please ask and answer questions here

CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.2.0, available at https://www.contributor-covenant.org/version/1/2/0/code-of-conduct.html

MAINTAINERS

@@ -0,0 +1,2 @@
+Diogo Correia <[email protected]> (@dvcorreia)
+Rui Martins <[email protected]> (@ruimartinsptl)

Makefile

@@ -1,26 +1,52 @@
-.PHONY: help build init upgrade/theme
+.PHONY: help build init upgrade-theme
 
 default: help
 
-help: # Show help for each of the Makefile recipes.
-	@echo ""
-	@echo "██╗  ██╗ █████╗ ██████╗ ██████╗ ██╗    ██╗ █████╗ ██████╗ ███████╗     ██████╗██╗████████╗██╗   ██╗"
-	@echo "██║  ██║██╔══██╗██╔══██╗██╔══██╗██║    ██║██╔══██╗██╔══██╗██╔════╝    ██╔════╝██║╚══██╔══╝╚██╗ ██╔╝"
-	@echo "███████║███████║██████╔╝██║  ██║██║ █╗ ██║███████║██████╔╝█████╗      ██║     ██║   ██║    ╚████╔╝ "
-	@echo "██╔══██║██╔══██║██╔══██╗██║  ██║██║███╗██║██╔══██║██╔══██╗██╔══╝      ██║     ██║   ██║     ╚██╔╝  "
-	@echo "██║  ██║██║  ██║██║  ██║██████╔╝╚███╔███╔╝██║  ██║██║  ██║███████╗    ╚██████╗██║   ██║      ██║   "
-	@echo "╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝  ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝     ╚═════╝╚═╝   ╚═╝      ╚═╝   "
-	@echo ""
-	@echo "                                                                           [email protected]"
-	@echo "Usage: make [target]"
-	@grep -E '^[a-zA-Z0-9 -]+:.*#'  Makefile | sort | while read -r l; do printf "* \033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done
-	@echo ""
-
-build: # Build the site.
-	hugo --minify --environment production
+##@ Getting Started
 
-init: # Initialize the theme submodule.
+init: ## Initialize the theme submodule and npm dependencies.
 	git submodule update --init
+	npm install
+
+run: ## Servers the site for development.
+	hugo serve -D --noHTTPCache
+
+build: ## Build the site.
+	hugo --minify --environment production
 
-upgrade/theme: # Upgrade the theme submodule.
+##@ Updates
+
+upgrade-theme: ## Upgrade the theme submodule.
 	git submodule update --remote --merge
+
+
+FORMATTING_BEGIN_YELLOW = \033[0;33m
+FORMATTING_BEGIN_BLUE = \033[36m
+FORMATTING_END = \033[0m
+
+help: # Show help for each of the Makefile recipes.
+	@printf -- "${FORMATTING_BEGIN_BLUE}%s${FORMATTING_END}\n" \
+	"" \
+	"  ██╗  ██╗ █████╗ ██████╗ ██████╗ ██╗    ██╗ █████╗ ██████╗ ███████╗" \
+	"  ██║  ██║██╔══██╗██╔══██╗██╔══██╗██║    ██║██╔══██╗██╔══██╗██╔════╝" \
+	"  ███████║███████║██████╔╝██║  ██║██║ █╗ ██║███████║██████╔╝█████╗  " \
+	"  ██╔══██║██╔══██║██╔══██╗██║  ██║██║███╗██║██╔══██║██╔══██╗██╔══╝  " \
+	"  ██║  ██║██║  ██║██║  ██║██████╔╝╚███╔███╔╝██║  ██║██║  ██║███████╗" \
+	"  ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝  ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝" \
+	"        .''.    *       .|                                          " \
+	"  *    :_\/_:           | |       *     ██████╗██╗████████╗██╗   ██╗" \
+	"   .''.: /\ :      *    |'|   *        ██╔════╝██║╚══██╔══╝╚██╗ ██╔╝" \
+	"  :_\/_:'.:::.  ___    |  |      *     ██║     ██║   ██║    ╚████╔╝ " \
+	"  : /\ :_::::.-'   '-. |  |     .--'|  ██║     ██║   ██║     ╚██╔╝  " \
+	"   '..-'|':_.|  |    ||   '-__  |   |  ╚██████╗██║   ██║      ██║   " \
+	"     |' | |.    |    ||       | |   |   ╚═════╝╚═╝   ╚═╝      ╚═╝   " \
+	"  ___|  '-'     '    \"\"       '-'   '-                              " \
+	" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [email protected]" \
+	""
+	@awk 'BEGIN {\
+	    FS = ":.*##"; \
+	    printf                "Usage: ${FORMATTING_BEGIN_BLUE}OPTION${FORMATTING_END}=<value> make ${FORMATTING_BEGIN_YELLOW}<target>${FORMATTING_END}\n"\
+	  } \
+	  /^[a-zA-Z0-9_-]+:.*?##/ { printf "  ${FORMATTING_BEGIN_BLUE}%-34s${FORMATTING_END} %s\n", $$1, $$2 } \
+	  /^.?.?##~/              { printf "   %-46s${FORMATTING_BEGIN_YELLOW}%-46s${FORMATTING_END}\n", "", substr($$1, 6) } \
+	  /^##@/                  { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

README.md

@@ -1,24 +1,90 @@
 # Hardware City website
 
+<img align="right" width="400" src="static/img/hardware-city-logo.svg">
+
 This is the source code for the Hardware City website.
 
-## How to set up
+With ❤️ from [Hardware City](https://hardwarecity.org)
+
+## Getting Started
+
+If you have any trouble getting started, reach out to us in our [Discord](https://discord.gg/mF3na6DY) or by email (see the [MAINTAINERS](./MAINTAINERS) file).
+
+### How to set up
+
+> [!NOTE]  
+> **For an optimal developer experience, it is recommended to install [Nix](https://nixos.org/download.html) and [direnv](https://direnv.net/docs/installation.html).**.
+
+<details><summary><i>Installing Nix and direnv</i></summary><br>
+
+**Note: These are instructions that _SHOULD_ work in most cases. Consult the links above for the official instructions for your OS.**
+
+Install Nix:
+
+```sh
+sh <(curl -L https://nixos.org/nix/install) --daemon
+```
+
+Consult the [installation instructions](https://direnv.net/docs/installation.html) to install direnv using your package manager.
+
+On MacOS:
+
+```sh
+brew install direnv
+```
+
+Install from binary builds:
+
+```sh
+curl -sfL https://direnv.net/install.sh | bash
+```
+
+The last step is to configure your shell to use direnv. For example for bash, add the following lines at the end of your `~/.bashrc`:
+
+    eval "\$(direnv hook bash)"
+
+**Then restart the shell.**
+
+For other shells, see [https://direnv.net/docs/hook.html](https://direnv.net/docs/hook.html).
+
+**MacOS specific instructions**
+
+Nix may stop working after a MacOS upgrade. If it does, follow [these instructions](https://github.com/NixOS/nix/issues/3616#issuecomment-662858874).
+
+<hr>
+</details>
+
+Otherwise, install the required dependencies.
+
+<details><summary><i>Installing required dependencies</i></summary><br>
+
+Install hugo following the instructions at <a href="https://gohugo.io/installation/">Hugo's Website</a>.
+
+Install Node JS >= 18.
+You can use `brew install node` on MacOS. For other systems, search on Google or download the installer at <https://nodejs.org/en/download/current>.
+
+<hr>
+</details>
+
+Then initialize the project with:
+
 ```bash
 make init
-npm install postcss-cli  # TODO(Rui): Move this line to the Makefile?
 ```
 
-## How to run
+### How to run
 
 ```bash
-make build
-hugo serve # -p 1313 --bind 127.0.0.1
+make run # then go to http://localhost:1313 on your browser
 ```
 
-<!--
-## How to contribute
 
--->
+## Community, discussion, contribution, and support
 
----
-With ❤️ from [Hardware City](https://hardwarecity.org)
+Contributions are made to this repo via Issues and Pull Requests (PRs).
+Opening an issue will show a set of templates and communication channels for you to use.
+If any part of the project has a bug or mistake, please let us know by opening an issue.
+
+### Code of conduct
+
+By participating and contributing to this project, you agree to uphold our [Code of Conduct](./CODE_OF_CONDUCT.md).

config/_default/hugo.yaml

@@ -2,9 +2,9 @@
 # Your theme name
 theme: "dot-org-hugo-theme"
 # Title of your website (required).
-title: "Dot Org Theme Demo"
+title: "Hardware City"
 # Default time zone for time stamps; use any valid tz database name: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
-timeZone: "America/Los_Angeles"
+timeZone: "Europe/Lisbon"
 
 ######################## i18n ####################
 # Auto-detect Chinese/Japanese/Korean Languages in the content. see: https://gohugo.io/getting-started/configuration/#hascjklanguage

package.json

@@ -1,24 +1,20 @@
 {
-  "name": "dot-org-hugo-theme",
+  "name": "hardwarecity-website",
   "version": "1.0.0",
   "description": "",
   "main": "none.js",
-  "scripts": {
-    "build": "hugo --theme=dot-org-hugo-theme",
-    "start": "hugo serve --logLevel info --configDir=config --buildDrafts --buildFuture --ignoreCache --disableFastRender --gc  --printI18nWarnings --printMemoryUsage --printPathWarnings --printUnusedTemplates --templateMetrics --templateMetricsHints",
-    "dev": "hugo serve --logLevel info --configDir=config --themesDir=../.. --buildDrafts --buildFuture --ignoreCache --disableFastRender --gc  --printI18nWarnings --printMemoryUsage --printPathWarnings --printUnusedTemplates --templateMetrics --templateMetricsHints"
-  },
+  "scripts": {},
   "repository": {
     "type": "git",
-    "url": "https://github.com/cncf/dot-org-hugo-theme"
+    "url": "https://github.com/HardwareCity/hardwarecity.github.io"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "bugs": {
-    "url": "https://github.com/cncf/dot-org-hugo-theme/issues"
+    "url": "https://github.com/HardwareCity/hardwarecity.github.io/issues"
   },
-  "homepage": "https://github.com/cncf/dot-org-hugo-theme#readme",
+  "homepage": "https://github.com/HardwareCity/hardwarecity.github.io#readme",
   "dependencies": {
     "autoprefixer": "^10.4.16",
     "hugo-extended": "^0.117.0",