Merge pull request #12 from ucla-imls-open-sci/datasquad-website-guide

Datasquad website guide

Gemfile.lock

@@ -12,6 +12,7 @@ GEM
     ffi (1.15.5)
     forwardable-extended (2.6.0)
     google-protobuf (3.24.2-arm64-darwin)
+    google-protobuf (3.24.2-x86_64-darwin)
     google-protobuf (3.24.2-x86_64-linux)
     http_parser.rb (0.8.0)
     i18n (1.14.1)
@@ -72,6 +73,8 @@ GEM
     safe_yaml (1.0.5)
     sass-embedded (1.66.1-arm64-darwin)
       google-protobuf (~> 3.23)
+    sass-embedded (1.66.1-x86_64-darwin)
+      google-protobuf (~> 3.23)
     sass-embedded (1.66.1-x86_64-linux-gnu)
       google-protobuf (~> 3.23)
     terminal-table (3.0.2)
@@ -82,6 +85,7 @@ GEM
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
+  x86_64-darwin-21
   x86_64-linux
 
 DEPENDENCIES

docs/datasquad-website-guide/add-link-btn.md

@@ -0,0 +1,47 @@
+---
+title: Add Button with Link
+layout: default
+parent: DataSquad Website Guide
+nav_order: 2
+
+---
+
+# Adding Button with Link
+1. **In the [Datasquad repository](https://github.com/UCLA-DataSquad/ucla-datasquad.github.io) (or it can be your local repository), navigate to `_data/sitetext.yml` file.**\
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-link-btn/step1.jpg" alt="step1" width="400"/>
+
+2. **In the section where you want to add the button, add the following lines:**
+    - I will be referring to your desired section as `[your-desired-section]`. In my case, it will be the `about` section.
+    ```
+    button: [your-button-title]
+    buttonlink: [your-desired-link]
+    ```
+    - Note that I will be adding the button in the `About` section, so I go to the `about` section in `sitetext.yml`, and add the follwing lines:
+    ```
+    button: Here's a button with a link
+    buttonlink: https://github.com/UCLA-DataSquad/ucla-datasquad.github.io
+    ```
+    - what it should look like in the file: \
+     <img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-link-btn/step2.jpg" alt="step2" width="600"/>
+
+3. **Navigate to `_includes/[your-desired-section].html`.**
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-link-btn/step3.png" alt="step3" width="400"/>
+
+4. **Paste the following lines:**
+
+    ```
+    {% raw %}
+    {%- if site.data.sitetext[site.locale].[your-desired-section].button -%}
+    <a class="btn btn-primary btn-xl text-uppercase js-scroll-trigger" href="{{ site.data.sitetext[site.locale].[your-desired-section].buttonlink }}">{{ site.data.sitetext[site.locale].[your-desired-section].button }}</a>
+    {%- endif -%}
+    {% endraw %}
+    ```
+    - Note that in the actual file, you need to change all `[your-desired-section]` to the actual section name where you want the button to be.
+    - The file should look something like this. Notice that all `[your-desired-section]` has been changed to `about`:
+    <img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-link-btn/step4.png" alt="step4" width="600"/>
+
+5. **Once you push your changes to the main branch, you should see the button in your desired section:**\
+    - Make sure to click it and check that it links to a correct website!
+    <img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-link-btn/step5.png" alt="step5" width="800"/>
+
+6. **Congrats! You added a button to the website! 🎉👏👏👏**

docs/datasquad-website-guide/add-projects.md

@@ -0,0 +1,39 @@
+---
+title: Add Projects
+layout: default
+parent: DataSquad Website Guide
+nav_order: 1
+
+---
+
+# Adding New Projects under "Projects" section
+1. **In the [Datasquad repository](https://github.com/UCLA-DataSquad/ucla-datasquad.github.io) (or it can be your local repository), navigate to `_portfolio` folder.**
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-project/step1.png" alt="step1" width="300"/>
+
+2. **Create a new `.md` file in the folder and name it appropriately.**
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-project/step2.png" alt="step2" width="300"/>
+
+3. **Copy the front matter from any of the other project files in `_portfolio` folder.**
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-project/step3.png" alt="step3" width="600"/>
+
+4. **Paste the front matter into the project file you created.**
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-project/step3-1.png" alt="step4" width="600"/>
+
+5. **Edit the front matter so it reflects the content of your project.**
+    - `title`: the title of your project.
+    - `thumbnail`: the path to the thumbnail image of your choice. You can add a new image under `assets/img/portfolio`. 
+    - `subtitle`: subtitle that goes under the main title. This is optional.
+    - `alt`: alternate caption for your image.
+    - `image`: path to the image you want to be displayed once the project card is clicked. Usually matches `thumbnail`, but it can also be any other image of your choice.
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-project/step4.png" alt="step5" width="600"/>\
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-project/step4-1.png" alt="step5" width="300"/>
+
+6. **Add content to your project.**
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-project/step4-2.png" alt="step6" width="600"/>
+
+7. **Once you push your changes to the main branch, you should see something like this:**
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-project/step5.png" alt="step7" width="800"/>\
+This is what it looks like when you click on the project card:
+<img src="{{ site.baseurl }}/assets/img/datasquad-website-guide/add-project/step5-1.png" alt="step7" width="800"/>
+
+8. **Congrats! You just published your project to the DataSquad Website! 🎉👏👏👏**

docs/datasquad-website-guide/blogs.md

@@ -0,0 +1,43 @@
+---
+title: Add/Manage Blogs
+layout: default
+parent: DataSquad Website Guide
+---
+
+# Adding Blogs
+
+1. Navigate to the `_posts` directory
+
+2. On the top right corner: Add file -> create new file 
+
+    ![create new blog]({{ site.baseurl }}/assets/img/datasquad-website-guide/add-blogs/add-blog-2.png)
+
+    **Note** The naming convention of these .md files is important, and must follow the format: '`YEAR-MONTH-DAY-title.MARKUP`'. The permalinks can be customized for each post, but the date and markup language are determined solely by the file name.
+
+3. Update the title, layout and author of the file
+
+    ![update blog information]({{ site.baseurl }}/assets/img/datasquad-website-guide/add-blogs/add-blog-3.png)
+
+4. Your new blog should now show up on the website after you push and deploy your changes! 
+
+    ![blog post displayed on site]({{ site.baseurl }}/assets/img/datasquad-website-guide/add-blogs/add-blog-4.png)
+
+# Highlighting Blogs
+
+To highlight a blog, add this section to the top of the post.
+
+![Blog Highlight Front-matter]({{ site.baseurl }}/assets/img/datasquad-website-guide/add-blogs/highlight-1.png)
+
+1. You need to have ``` showcase: 1 ```, this will signifiy that you wan the blog highlighted.
+
+2. You need to add the ``` card ``` section. This section is exactly like a project card except for the last two variables. Refer to [Add Projects]({{ site.baseurl }}/docs/datasquad-website-guide/add-blogs/add-projects)
+
+3. ``` intro: ``` This is what is going to be displayed on the blog card. Write a short introduction to the blog here.
+
+4. ``` url: ``` The url should be the date followed by the file name in the following format: ```YYYY/MM/DD/File_name```
+
+After adding this to a blog post, it should appear like the following on the webpage:
+
+![Blog Card]({{ site.baseurl }}/assets/img/datasquad-website-guide/add-blogs/highlight-2.png)
+
+![Blog Card]({{ site.baseurl }}/assets/img/datasquad-website-guide/add-blogs/highlight-3.png)

docs/datasquad-website-guide/datasquad-website-guide.md

@@ -0,0 +1,10 @@
+---
+title: DataSquad Website Guide
+layout: default
+permalink: /docs/datasquad-website-guide
+has_children: true
+---
+
+Refer to [Add Projects]({{ site.baseurl }}/docs/datasquad-website-guide/add-projects) and 
+[Add/Manage Blogs]({{ site.baseurl }}/docs/datasquad-website-guide/blogs) to add projects/blogs. 
+If you have any issues with Projects/Blogs loading on the site refer to [Debugging]({{ site.baseurl }}/docs/datasquad-website-guide/debugging)

docs/datasquad-website-guide/debugging.md

@@ -0,0 +1,61 @@
+---
+title: Debugging
+layout: default
+parent: DataSquad Website Guide
+---
+
+If you have any issues with either your blog highlight or project card showing up read this documentation.
+
+## Check Github Actions
+First, check for any **Github Action** errors. If there are any errors it may mean that the workflow designed to update
+the site failed. To navigate to the potential source of error follow the steps below:
+
+1. Navigate to **Github Actions** in the [DataSquad Site Repo](https://github.com/UCLA-DataSquad/ucla-datasquad.github.io)
+
+    ![Github Actions]({{ site.baseurl }}/assets/img/datasquad-website-guide/debugging/actions-1.png)
+
+2. Look at the most recent workflows, if there is no workflow with an X then that means everything completed perfectly and you can move on. 
+If not it looks like:
+
+    ![Workflow]({{ site.baseurl }}/assets/img/datasquad-website-guide/debugging/actions-2.png)
+
+3. Click on the failed workflow and look through it and see what failed. If the workflow failed because of jekyll being unable to run
+that means that there is code in your most recent commit that breaks jekyll. Look through the changes you've made and try to identifiy any code
+that may have done so. If you click deeper into the workflow it may tell you what the error is.
+
+    ![Workflow Error]({{ site.baseurl }}/assets/img/datasquad-website-guide/debugging/actions-3.png)
+    ![Workflow Error Details]({{ site.baseurl }}/assets/img/datasquad-website-guide/debugging/actions-4.png)
+
+## Check the Repository
+
+Now if your workflow error has a specific about what went wrong with jekyll follow the error message and locate your bug. If your workflow error has
+nothing to do with jekyll or it has no error at all follow the steps below. If you don't care how it works skip to **step 5**
+
+1. **Count the number of files in the _posts folder.**
+
+    The following example has 5 posts.
+
+    ![Post Count]({{ site.baseurl }}/assets/img/datasquad-website-guide/debugging/repo-1.png)
+
+2. **Check the _includes/modals.html file.**
+
+    Look for the following line of code  \
+    {% raw %} `{% assign modified_index = forloop.index | plus: %}`. {% endraw %} 
+    You can `ctrl/cmd + f` the following to find it: `assign modified_index`
+
+    ![modals.html]({{ site.baseurl }}/assets/img/datasquad-website-guide/debugging/repo-2.png)
+
+    Notice how the number after `plus` doesn't align with the number of blog posts. The error exists here and you should change it to the appropriate
+    number of blogs.
+
+3. **Check the _includes/portfolio_grid.html file.**
+
+    Look for the same line of code as _includes/modals.html If there are any discrepancies with the code make that fix.
+
+4. Run Jekyll locally with the `bundle exec jekyll serve` command and see if your blog/project appears.
+
+5. To avoid doing all of that work you can just run the *blog_script,sh* with the following command:
+    `./blog_script.sh`
+
+If this does not solve your issue, then you will have to debug for the issue on your own. A good start is to look at the files
+you have added/modified and work backwards from there until you reach the source of error.

docs/website-guide/add-blog.md → docs/imls-website-guide/add-blog.md

@@ -1,7 +1,7 @@
 ---
 title: Add blog
 layout: default
-parent: Website Guide
+parent: IMLS Website Guide
 nav_order: 1
 ---
 

docs/website-guide/add-images.md → docs/imls-website-guide/add-images.md

@@ -1,7 +1,7 @@
 ---
 title: Add image
 layout: default
-parent: Website Guide
+parent: IMLS Website Guide
 nav_order: 2
 ---
 

docs/website-guide/add-tab.md → docs/imls-website-guide/add-tab.md

@@ -1,7 +1,7 @@
 ---
 title: Add tab
 layout: default
-parent: Website Guide
+parent: IMLS Website Guide
 nav_order: 3
 ---
 

docs/imls-website-guide/timeline.md

@@ -0,0 +1,7 @@
+---
+title: Add tab
+layout: default
+parent: IMLS Website Guide
+nav_order: 4
+---
+

docs/website-guide/website-guide.md → docs/imls-website-guide/website-guide.md

@@ -1,5 +1,5 @@
 ---
-title: Website Guide
+title: IMLS Website Guide
 layout: default
 permalink: /docs/website-guide
 has_children: true