How to contribute to the developer portal
We wanted to build an open and inclusive, easy to use developer portal that offers guidance and allows community contribution. To achieve this we have chosen Docusaurus 2, a modern static website generator.
Installation#
To contribute to the Cardano developer portal, you must first install it locally.
Requirements#
- Node.js version >= 12.13.0 or above (which can be checked by running
node -v). You can use nvm for managing multiple Node versions on a single machine installed. - Yarn version >= 1.5 (which can be checked by running
yarn --version). Yarn is a performant package manager for JavaScript and replaces thenpmclient. It is not strictly necessary but highly encouraged. - On macOS you also need Xcode and Command Line Tools.
Local development#
To get a local development environment, clone the repository, navigate into the developer-portal folder, install dependencies, and start the development server. Most changes are reflected live without having to restart the server. By default, a browser window will open at http://localhost:3000.
git clone https://github.com/cardano-foundation/developer-portal.gitcd developer-portalyarn installyarn startLimitations of the development build
The development mode will have minor features not working. For example, only blurry images in the responsive images on showcase and tools, search limitations, and some data has fake values because of performance reasons.
Production build#
yarn buildUse this command instead of yarn start to generate static content into the build directory that can be served using any static content hosting service.
Project structure#
The portal is structured as follows. (See the Project structure rundown below for details)
developer-portal├── blog│ ├── 2021-01-07-january.md│ ├── 2021-02-03-february.md│ └── *.md├── docs│ ├── fund-your-project│ ├── get-started│ ├── integrate-cardano│ ├── native-tokens│ ├── operate-a-stake-pool│ ├── stake-pool-course│ ├── transaction-metadata│ └── *.md├── examples│ ├── cli│ | ├── dotnet│ │ │ └── *.cs│ | ├── js│ │ │ └── *.js| | └── python│ │ └── *.py| └── wallets│ ├── dotnet│ ├── js| └── python├── src│ ├── css│ │ └── custom.css│ ├── data│ │ ├── builder-tools│ │ │ └── *.png│ │ ├── showcase│ │ │ └── *.png│ │ ├── builder-tools.js│ │ └── showcases.js│ └── pages│ ├── styles.module.css│ └── index.js├── static│ └── img├── docusaurus.config.js├── package.json├── README.md├── sidebars.js└── yarn.lockProject structure rundown#
/blog/- Contains the blog Markdown files for the developer spotlight./docs/- Contains the Markdown files for the docs. Customize the order of the docs sidebar insidebars.js./examples/- Contains example projects for the Markdown files in the docs. The structure is not final and will likely change in the future/src/- Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here, but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing./src/data/builder-tools- Screenshots for the builder tools section./src/data/builder-tools.js- Definition file for the builder tools section./src/data/showcase- Screenshots for the showcase section./src/data/showcase.js- Definition file for the showcase section./src/pages- Any files within this directory will be converted into a website page.
/static/- Static directory. Any contents inside here will be copied into the root of the finalbuilddirectory./docusaurus.config.js- A config file containing the site configuration./package.json- A Docusaurus website is a React app. You can install and use any npm packages you like in them./sidebar.js- Used by the documentation to specify the order of documents in the sidebar.