Qiskit's website

⚛️ 💻

⚠️ IMPORTANT UPDATE

We renamed the master branch to main and GitHub is displaying a notice for the contributors visiting the repository. However, this is not compatible with the Forking Workflow we follow in the team. If you are contributing to qiskit.org, chances are that you have a fork of this project and your origin remote is pointing to it. The Qiskit/qiskit.org repository should be your upstream remote and so, the instructions provided by GitHub should be directed towards your upstream remote:

git branch -m master main
git fetch upstream
git branch -u upstream/main main

Welcome to Quantum

Qiskit is an open-source quantum computing software development framework for leveraging today's quantum processors in research, education, and business.

Home page · Learn · Documentation · Advocates · Support: Slack

What’s In This Document

• What’s In This Document
• ⚡️ Live
• 💻 Technology Used
• 🚀 Get Up and Running
• 🏭 Content Generation
• 🎚️Other environment flags
  • Enable analytics
• 🧐 Folder Structure
• ✏️ How to Contribute
• 🛠 Available Scripts
• 🗓 Open backlog
• 👩‍💻 Maintainers

⚡️ Live

Go to Qiskit.org's website

💻 Technology Used

Qiskit.org is a pre-rendering SPA using Nuxt.js.

A pre-rendering SPA is a single page application that generates a static markup (HTML) at build time. The user, when entering the web, receives HTML (as if it were a static web) but in the meantime, JS files belonging to the SPA are loaded “hydrating” the web until it's completely dynamic.

Nuxt.js is the biggest framework on top of Vue.js to generate universal SPAs. Universal or "isomorphic" apps can be pre-rendering or SSR. Since so far we don't need server functions, our website it's just pre-rendering.

We create and run unit tests using Jest, ensure avoiding syntax errors using ESLint and automate all these previous tools and deployment using Travis.

With this technology we want to achieve:

• Separation between content edition and development concerns.
• Use a component based framework like Vue that allow us to reuse part of the UI code in different parts of the application.
• Fast initial page load.
• Index content on Search Engines.
• Test JS unit functions.
• Avoid syntax errors.
• Continuous integration pipeline.

🚀 Get Up and Running

1. Download this repository and go to its folder

   git clone git@github.com:Qiskit/qiskit.org.git && cd qiskit.org

2. Install dependencies

    npm install

3. Run a local server with hot reload at localhost:3000

   npm run dev

🏭 Content Generation

qiskit.org integrates with the tools used by the IBM Quantum Community Team and generate some content based on 3rd party APIs such as Airtable. Part of this content is prefetched during building time. While developing, it is disabled by default. If you want enable content generation, you must set the environment variable GENERATE_CONTENT. For instance:

GENERATE_CONTENT=1 npm run dev

Notice that, for communicating with the team tools, API keys may be required. It is the case of dealing with Airtable for the generation of the event index. If you think you should have access to these tables, talk to the Event Squad in the Community Team, get your developer API key and set the AIRTABLE_API_KEY environment variable to this value:

GENERATE_CONTENT=1 AIRTABLE_API_KEY=<your airtable api key> npm run dev

🎚️Other environment flags

Enable analytics

In production, the user can authorize us to gather analytics so we can identify trends and improve our user experience. In development, analytics are disabled by default. To enable, set the ENABLE_ANALYTICS environment variable.

🧐 Folder Structure

.
├── app
├── assets
├── components
├── constants
├── content
├── deploy
├── hooks
├── layouts
├── mixins
├── new-content
├── pages
├── plugins
├── static
├── store
├── tests
├── nuxt.config.js
... other third-parties configuration files like ESLint, Jest or Travis

1. /app: contains router.ScrollBehavior.js controlling the behavior of the scroll when navigating.

2. /assets: Images and assets for the project. You can find more information at Nuxt's assets directory documentation

3. /components: Vue components for the project. You can find more information at Nuxt's components directory documentation

4. /constants: Constants shared through the whole project.

5. /content: Markdown files, website's editable content. They are divided in folders by sections.

6. /deploy: Deploy configuration.

7. /hooks: Hook functions shared through the whole project.

8. /layouts: You can find information at Nuxt's layout directory documentation

9. /mixins: Mixin functions shared through the whole project.

10. /new-content: This directory includes newer content that is used in various parts of the qiskit.org website, leveraging the nuxt/content module, along with standard markdown syntax.

11. /pages: This is a starting point because if you want to know what is the website structure, it's the same as this folder's structure. Nuxt reads all the .vue files inside this directory and creates the application router based on it. You can find information at Nuxt's pages directory documentation. All .vue pages prefixed by an underscore are dynamic routes and we use them to create different pages based on the same template. We also use nuxt-link to keep the user inside our webapp router.

12. /plugins: You can find information at Nuxt's plugins directory documentation

13. /statics: You can find information at Nuxt's statics directory documentation

14. /tests: Unit tests made with Jest

15. /types: Additional types for non-typed libraries or global definitions.

16. nuxt-config.js: This is the main configuration file for a Nuxt site. You can find information at Nuxt's config documentation

✏️ How to Contribute

Contributions are always welcome, no matter how large or small. Before contributing, please read the contributing guide and code of conduct.

🛠 Available Scripts

Run a local server enabling inspector agent:

  npm run dev-debug

Run unit tests made with Jest:

  npm run test

Build static version ready for production, output will generated inside a new folder called dist:

  npm run build

Run a local server on the website's production built. Make sure you ran npm run build first:

  npm run start

Find syntax errors. We use ESLint:

  npm run lint

Autofix linter:

  npm run fix-lint

🗓 Open backlog

You can see our backlog here.

👩‍💻 Maintainers

In alphabetical order:

Abdón Rodríguez 🐛💻💬	Eddybrando Vásquez 🐛💻💬	Gregorio Iniesta 🐛💻💬	Leron Gil 🐛💬
Randy Tolentino 🐛💻💬	Russell Huffman 🎨💬	Salvador de la Puente 🐛💻💬	Yaiza García 🐛💻💬