Skip to content

Home

Jump to bottom
tobyegg edited this page Jan 20, 2023 · 16 revisions

JIPCAD Website Editing Tutorial

The intention of starting the JIPCAD website is to host and maintain JIPCAD documentation, as well as allow for a place where the amazing creations of URAP members and users are exhibited. Every JIPCAD contributor is encouraged to update and improve the JIPCAD documentation and post on the blog display your creations and detail your methods behind their creation. It's also vastly helpful to contribute to the general Q&A page to report and document any bug or bummer you have encountered while using the software so other users can avoid spending mass amounts of time reinventing the wheel. Now let's dive into how to locally host the repository, the structure of the website, and where should you put your additions.

1. Installation

The NOME website is built using docusaurs, which extends yarn, and thus requires Node.js to run.

1.0 Github

If not already installed, download Github Desktop and clone the repository to a blank folder.

1.1 Node.js

Setup:

  • Mac and Windows, download the installer for the 16.14.0 version of Node.js found on their website
    • This is found on the 5th page of the "Previous Releases" menu
    • Check all boxes during install
    • Alternatively, get NVM for Windows or NVM if on Mac, this lets you switch between and install different version with ease. This is recommended, as sometimes features break in a certain version of node, and without NVM switching can be difficult.
  • Linux: 64-bit and ARMv7/8 binaries are available at the above link

On any terminal, run node -v to check if it has been successfully installed

1.2 Yarn

JIPCAD.github.io is built using a legacy version of yarn, v1.22.15, meaning that classic.yarnpkg.com should be used for installation/troubleshooting information and not the modern website for v2 and more recent yarn. First time-setup:

  • Navigate to the repository folder in terminal
  • Run yarn or yarn install (they are identical commands)
  • Check if yarn is installed with yarn -v. Now that yarn is installed, running yarn or yarn install will check if yarn is up to date.

Congratulations! You've locally built JIPCAD.github.io. To host, run yarn start and a browser window will open with your version of the website. Here, you can edit files, compare to the original, and when ready, push to the repository!

1.3 Notes

  • All commands must be run on an administrator command-level; on a Windows computer with multiple profiles, this means the terminal must be right-clicked and run as administrator on any but default user.
    • A shortcut for this is to hit windows key, type "cmd", and ctrl+shift+enter
  • Do not update yarn when first installing it, this will overwrite the provided docusaurus commands. Simply run yarn to install v1.22.19
  • If the website displays warnings about "unmet peer dependency" or compiles with errors when running yarn start, uninstall node (through standard Windows/OSX uninstall app function) and reinstall v.16.13.10 (steps)
  • While the website is running locally, use ctrl+c or cntrl+pause to end the hosting.
  • "npx" commands are built into docusaurus/yarn and can be run after following the above steps. "npm" commands refer to the npm package manager, which may or may not be installed with node depending on the method of installation (version can be checked with npm -v). "nvm" commands are commands for Node Version Manager or Node Version Manager for Windows, which are two separate projects. Chocolately is a package handler which may be present on your computer if Node was installed using a downloaded installer.

2. Website Structure

The current JIPCAD documentation includes the following parts

  • Documentation
    • Introduction
      • The general introduction which explains what is JIPCAD and why it's initiated.
    • Compiling
      • The compiling guide shows you the compiling procedure of the software from the source code.
    • Tutorial
      • User Guide
        • The user guide doesn't touch the code part.
        • This session includes how to use JIPCAD software.
        • Examples that tell you how to advance the JIPCAD tool.
      • Developer Guide
        • The developer guide is for those who intend to contribute to the JIPCAD code base.
        • The general mechanism of how the code works.
        • Gives you an idea of what different parts of the code do.
        • The data structures and dependencies used in the codebase.
        • Once your interest is set, which part of the code should you read and touch.
    • JIPCAD language reference
      • Configuration
        • The configurations of the JIPCAD file.
      • Numerical Parameters and Sliders
        • Use of sliders
        • Time-varying models​
      • Generators
        • How to generate all available geometric shapes
      • Rendering Specifications
      • Numerical Parameters and Sliders
      • Generators
      • Rendering Specifications
    • Error Reporting
      • As the JIPCAD software is in development, the error reporting reveals the current imperfections you should be aware of.
      • Host crashes and bugs each URAP member encounters:
        • If you have made things work, how?
        • If things unfortunately failed, which file and what operations have led to the happening?
  • Exhibition
    • The exhibition page is set up for showing all works completed by JIPCAD artists.
    • The inclusion of detailed steps which have led you to the creation of the masterpiece is appreciated.
  • Download
    • The download page keeps the Mac and Windows executables.
    • Version management should be maintained on this page to keep logging the updates and new features of JIPCAD software.

2.1 Contributing to the Website: Tips & Tricks

2.1.0: Workflow

  • Some things are easy to edit in a Docusaurus website, some things are hard. When updating the website, I highly suggest you follow this or a similar method:
    • Go through every page on the live website, making a paper list of what edits you want where. Have headers for each page of the website and bullet points for edits. Indent headers and bullet points to match page structure.
    • Go through your list of edits and mark them with a number 1-4, describing the difficulty of the edit:
    • 1: minor edits (e.g. grammar, broken images links) to existing pages.
    • 2: new pages, docs and blog posts go here.
    • 3: organizational issues to be solved, such as sidebar out of alignment or resizing images. Included here also would be organizational work on the website's files themselves, such as sorting assets into folders for ease of use. Addition of categories to the website (such as a new horizontal section beyond Documentation, Exhibition, and Downloads) should go here.
    • 4: new functionality to be added to the website, which will likely require manipulation of the website's foundations.
    • Work through your list in the order of easiest to hardest. Generally 2 will take the greatest amount of time and 4 the greatest effort. When any single item is complete, cross it off your list with a bright-colored pen. When every line is visibly sliced through, do a final grammar pass and push your updated website. Congrats!
  • Use alt + x to move a line of text up & down the doc without copy-pasting (in VSCode).
  • You can and should leave the local website open when editing; whenever a file is saved on your computer, the local version will automatically update without having to stop and start again--however, it often takes two refreshes on the websites to see the new edits.
    • This behavior is visible by looking at the terminal running the localhost website; when a file is saved in VSCode, the website will update. If the website "compiles without error" but the behavior is not as you would expect it, the problem is in your coding.
  • The naming convention for any new assets or pages is all lowercase with dashes instead of spaces between words, as spaces can mess with docusaurus' automatic pathing.
  • On the whole, editing the website's files will do what you think it will do: adding a folder adds a sidebar level, adding a page adds a page to the website. Breaking the website can be fixed by simply deleting the new offending change, so don't be afraid to try strange things.

2.1.1: Markdown & Editing Docs

  • All pages in the Documentation tab of the website are edited in the docs folder.
  • For an intro to markdown, GeeksforGeeks is friendly, while Daring Fireball has more detailed information.
  • Info enclosed in --- at the top of a doc is metadata that helps arrange your page within the website. The most common ones are slug (allows for a custom path to the doc), sidebar_position (dictates how pages should be arranged from top to bottom of the sidebar in numbers, 1 is top), and title, but all options can be found on the Docusaurus website and can be quite helpful.
  • For coding dropdowns (the blue spoiler-text ones), add a blank line before and after and to avoid all kinds of errors.
  • a category.json file inside a folder holds the organizational metadata for the folder itself (i.e., where the folder should be on the sidebar). To make one yourself, just open an existing category file and ape the syntax.

2.1.2: Images

  • Add new images to both /img and /static/img folders. Adding new images to other directories is irrelevant but mostly harmless.
  • To reference images inside docs, use the /img/[IMAGE-NAME] path.
  • If hosted on the Internet, URLs can also be used--but keep in mind URLs break frequently. The stablest option is to download and include the image as an asset if legal to do so.

2.1.3: Blog

  • Add your information to the authors.yml file before adding blog posts. This makes it very easy to add your info in later posts by adding the authors: [YOUR-NAME] metadata at the top of the page.

2.1.4: Random Notes

When linking to other pages on the website, it is most stable to use the entire docs path. Ex: if I want to link to the Generators page, my markdown might look like this: this information can be found on the [generators page](docs/lang-ref/generators).

3. Website Management

3.1 Website Files

Edit the files in the corresponding folder to manage the website contents. Ensure that you are in the source branch.

The website uses docusaurus as the backbone, you could read the docusaurus doc for more instruction.

3.2 Website Deployment

In this website repo, there are two branches:

  1. deploy
    • Where the deployed built is hosted and what people see at the website.
    • Do not directly edit files at the deploy branch!!!
  2. source
    • Where the source code before the building is hosted.

Deploy to the JIPCAD.github.io page, use the following bash command:

GIT_USER=<GH username> USE_SSH=true yarn deploy
Clone this wiki locally