Feature: add MkDocs to build HTML and github actions to deploy the docs

.github/workflows/docs.yml

@@ -0,0 +1,22 @@
+name: Build and deploy doc pages
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install mkdocs-material>=9.0.0
+      - run: mkdocs gh-deploy --force

README.md

@@ -7,30 +7,6 @@ I've also noticed how few questions were asked by people I interviewed and I thi
 
 If you asked something not listed here, send in a PR.
 
-Translations:
-
-- [Arabic](https://github.com/viraptor/reverse-interview/blob/master/translations/ARABIC.md)
-- [Bulgarian](https://github.com/viraptor/reverse-interview/blob/master/translations/BULGARIAN-Cyrillic.md)
-- [Catalan](https://github.com/viraptor/reverse-interview/blob/master/translations/CATALAN.md)
-- Chinese [Simplified](https://github.com/yifeikong/reverse-interview-zh) / [Traditional](https://github.com/NeroCube/reverse-interview-zh-tw/blob/master/README.md)
-- [English](https://github.com/viraptor/reverse-interview/blob/master/README.md)
-- [French](https://github.com/viraptor/reverse-interview/blob/master/translations/FRENCH.md)
-- [German](https://github.com/viraptor/reverse-interview/blob/master/translations/GERMAN.md)
-- [Hindi](https://github.com/hraverkar/reverse-interview/blob/master/translations/Hindi.md)
-- [Indonesian](https://github.com/viraptor/reverse-interview/blob/master/translations/INDONESIAN.md)
-- [Italian](https://github.com/viraptor/reverse-interview/blob/master/translations/ITALIAN.md)
-- [Japanese](https://github.com/viraptor/reverse-interview/blob/master/translations/JAPANESE.md)
-- [Korean](https://github.com/JaeYeopHan/Interview_Question_for_Beginner/blob/master/Reverse_Interview/README.md)
-- [Persian](https://github.com/Kaaveh/reverse-interview/blob/master/translations/PERSIAN.md)
-- [Polish](https://github.com/viraptor/reverse-interview/blob/master/translations/POLISH.md)
-- [Portuguese (Brazilian)](https://github.com/viraptor/reverse-interview/blob/master/translations/pt-BR.md)
-- [Russian](https://github.com/kix/reverse-interview/blob/master/README.md)
-- Serbian [Latin](https://github.com/viraptor/reverse-interview/blob/master/translations/SERBIAN-Latin.md) / [Cyrillic](https://github.com/viraptor/reverse-interview/blob/master/translations/SERBIAN-Cyrillic.md)
-- [Spanish](https://github.com/felHR85/Entrevista-inversa/blob/master/README.md)
-- [Turkish](https://github.com/viraptor/reverse-interview/blob/master/translations/TURKISH.md)
-- [Ukrainian](https://github.com/viraptor/reverse-interview/blob/master/translations/UKRAINIAN.md)
-- [Vietnamese](https://github.com/tuannh99/reverse-interview/blob/master/README.md)
-
 ## Expected usage
 
 - Check which questions are interesting for you specifically
@@ -42,7 +18,7 @@ Definitely don't try to ask everything from the list. (Respect the interviewer's
 Remember that things tend to be fluid, re-organizations happens often.
 Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn't mean your time to deliver is necessarily short.
 
-# The Role
+## The Role
 
 - What's the on-call plan/schedule? (what's the pay for standby and call-out)
 - What are the tasks I would do on a usual day?
@@ -60,7 +36,7 @@ Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn
 - What management style does my immediate manager and their manager have? (from micro- to macro-)
 - How can I develop in my new role / what opportunities are offered?
 
-# Tech
+## Tech
 
 - What are the usual stacks used at the company?
 - How do you use source control?
@@ -82,7 +58,7 @@ Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn
 - How do you manage internal / external artifacts?
 - How do you manage dependencies?
 
-# The Team
+## The Team
 
 - How is the work organised?
 - How does the intra/inter-team communication typically work?
@@ -105,7 +81,7 @@ Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn
 - How big is each team?
 - How are services and projects delegated to each team?
 
-# Your Potential Coworkers
+## Your Potential Coworkers
 
 - Who do developers tend to learn from?
 - What do you like best about working there?
@@ -114,7 +90,7 @@ Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn
 - How long has the longest team member been there?
 - If it's a small team, has there been experiences of conflicting personalities and how was this dealt with?
 
-# The Company
+## The Company
 
 - Why is the company hiring? (product growth / new product / fluctuation / ...)
 - Is there a conference/travel budget and what are the rules to use it?
@@ -136,14 +112,14 @@ Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn
 - What kind of social events does the team/company host and are these attended by everyone?
 - Why did the company decide to hire an outsider over promoting an internal employee? 
 
-# Social issues
+## Social issues
 
 - What's the status of / view on diverse hiring?
 - What do you think are the gaps in the company culture? (and what is the company culture?)
 - What does work-life balance mean here?
 - Does the company have a stance regarding climate change?
 
-# Conflict
+## Conflict
 
 - How are differences of opinions resolved?
 - What happens after pushback? ("this can't be done in the projected time")
@@ -152,7 +128,7 @@ Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn
 - When there is a gap between expectations from management and performance of an engineer or team, what happens?
 - Could you tell me a story about a toxic situation and how the company dealt with it?
 
-# The Business
+## The Business
 
 - Are you profitable?
 - If not, how long is your runway?
@@ -163,7 +139,7 @@ Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn
 - What are the big challenges you see coming up?
 - What have you identified as your competitive advantage?
 
-# Remote Work
+## Remote Work
 
 - What's the ratio of remote to office workers?
 - Does the company provide hardware and what's the refresh schedule?
@@ -173,26 +149,26 @@ Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn
 - How often are office visits expected?
 - Are the office meeting rooms always prepared for video conferences?
 
-# Building Layout
+## Building Layout
 
 - What's the office layout? (open plan / cubicles / offices)
 - Is there a support / marketing / other call-heavy team close to my new team?
 
-# Catch all
+## Catch all
 
 - What's the best and what's the worst aspect of working in this role / team / company?
 - What got you to choose to work for the company initially?
 - What keeps you at the company?
 
-# Compensation
+## Compensation
 
 - If you have a bonus scheme, then how are bonuses determined?
 - If you have a bonus scheme, then what have been the typical bonus percentages over the past few years?
 - Do you have a 401k or other retirement plan? If so, does the company match additional plan contributions?
 - Are there medical benefits and if so, when do they start?
 - Do you pay for relocation?
 
-# Time Off
+## Time Off
 
 - How much Paid Time Off (PTO) is offered?
 - Are sick time and vacation time separate or do they come from the same pool?
@@ -202,15 +178,15 @@ Having a bug tracking system doesn't make bug handling efficient and CI/CD doesn
 - What is the policy on unpaid leave?
 - What is the policy for sabbatical leave?
 
-# Other resources
+## Other resources
 
 Find more inspiration for questions in:
 
   - [The Joel Test: 12 Steps to Better Code](https://www.joelonsoftware.com/2000/08/09/the-joel-test-12-steps-to-better-code/) by Joel Spolsky
   - [Questions I'm asking in interviews](https://jvns.ca/blog/2013/12/30/questions-im-asking-in-interviews/) by Julia Evans
   - [Curated list of salary negotiation advices](https://github.com/petermekhaeil/salary-negotiating) by Peter Mekhaeil
 
-# License
+## License
 
 [![Creative Commons License](https://i.creativecommons.org/l/by-sa/4.0/88x31.png)](https://creativecommons.org/licenses/by-sa/4.0/)
 

mkdocs.yml

@@ -0,0 +1,97 @@
+# RECOMMENDATION: set up the JSON schema as described in https://squidfunk.github.io/mkdocs-material/creating-your-site/#minimal-configuration
+# this will provide auto-completion and pop-up annotations of invividual parameters.
+# This configuration is heavily based on https://github.com/copier-org/copier/blob/master/mkdocs.yml
+site_name: "Reverse interview questions"
+# to be validated and filled according to the place where you push the repository
+# the git repo link in the header
+repo_url: https://github.com/viraptor/reverse-interview
+# the title to use for the git repo link
+repo_name: "reverse-interview"
+# main directory with markdown files (default is `docs`)
+docs_dir: translations
+# relative path to the markdown files on github
+edit_uri: blob/master/translations/
+
+nav:
+  - English: "README.md"
+  - Arabic: "ARABIC.md"
+  - Bulgarian: "BULGARIAN-Cyrillic.md"
+  - Catalan: "CATALAN.md"
+  - Chinese:
+      - Simplified [external]: https://github.com/yifeikong/reverse-interview-zh
+      - Traditional [external]: https://github.com/NeroCube/reverse-interview-zh-tw/blob/master/README.md
+  - French: FRENCH.md
+  - German: GERMAN.md
+  - Hindi: Hindi.md
+  - Indonesian: INDONESIAN.md
+  - Italian: ITALIAN.md
+  - Japanese: JAPANESE.md
+  - Korean [external]: https://github.com/JaeYeopHan/Interview_Question_for_Beginner/blob/master/Reverse_Interview/README.md
+  - Persian: PERSIAN.md
+  - Polish: POLISH.md
+  - Portuguese (Brazilian): pt-BR.md
+  - Russian [external]: https://github.com/kix/reverse-interview/blob/master/README.md
+  - Serbian:
+      - Cyrillic: SERBIAN-Cyrillic.md
+      - Latin: SERBIAN-Latin.md
+  - Spanish [external]: https://github.com/felHR85/Entrevista-inversa/blob/master/README.md
+  - Turkish: TURKISH.md
+  - Ukrainian: UKRAINIAN.md
+  - Vietnamese [external]: https://github.com/tuannh99/reverse-interview/blob/master/README.md
+
+theme:
+  name: material
+  # icon:
+  #   repo: fontawesome/brands/gitlab
+  features:
+    # enables annotations, see https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-annotations
+    - content.code.annotate
+    # for navigation features see https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/
+    - navigation.top
+    - navigation.tracking
+    # keep all sections in the navigation expanded by default
+    - navigation.expand
+    # add icon and link to the document on gihub for each page
+    - content.action.edit
+  icon:
+    # icon for the git repository link on the top-right
+    repo: fontawesome/brands/github
+    # icon for the view of the current page in the repository
+    edit: material/eye
+  palette:
+    # light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      # main theme color
+      primary: deep orange
+      # the color to change to for a hover on an interactive element
+      accent: amber
+      # definition of the  header icon for this mode
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    # dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      # main theme color
+      primary: deep orange
+      # the color to change to for a hover on an interactive element
+      accent: amber
+      # definition of the  header icon for this mode
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
+
+# use a long list of recommended extensions from https://squidfunk.github.io/mkdocs-material/setup/extensions/?h=pymdownx#recommended-configuration
+markdown_extensions:
+  # Python Markdown
+  - admonition
+  - toc:
+      permalink: true
+
+  # Python Markdown Extensions
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.tilde