Stellar developer portal site generator.
This uses gulp and metalsmith (plus a heap of plugins) to generate the site.
To build this project, you must have the following dependencies installed:
- node 10.16.3
- npm
- yarn
git clone https://github.com/stellar/developers # or git@github.com:stellar/developers.git
npm install --no-shrinkwrap
yarn install(Note the no-shrinkwrap option is because of an issue in metalsmith-concat: aymericbeaumet/metalsmith-concat#22)
The developers site tool generates content pulled in from other repos. These repositories are configured in repos.json and stored in repos/. To clone all the required repositories, run:
node_modules/.bin/gulp git:clone
Keeping these repositories up to date is the responsibility of the person using this tool. Here is a simple bash command you can use to do a git pull on all the repos.
for dir in ./repos/*;
do
if [[ -d $dir ]]; then
( echo; cd "$dir"; pwd; git pull );
fi;
done
To generate the static site, run the following inside your repo containing this folder:
node_modules/.bin/gulp # or just `gulp` if you have it installed globally or have path set upTo run a web server and view the site in a browser:
node_modules/.bin/gulp watch serveThis will also automatically rebuild the site when edits are made. (To serve without rebuilding, drop the watch argument.)
By default, the site is served under the developers/ subfolder. This is to reduce the amount of bugs when this site is deployed to https://www.stellar.org/developers/. This can be changed by passing a custom baseUrl to the gulp build task like so: gulp --baseUrl="/" or gulp build --baseUrl="/".
When working on the site, you can also use the --debug option to generate output that is easier to debug in the browser (it includes things like sourcemaps).
Browser JavaScript files live in src/js. vendor.js is generated from bower_components and not checked in to the repository.
To add a new browser JS file, add it to src/js and update the metalsmith concat step by adding your new file to the list. The list of JS files is order sensitive.
- Use yaml especially for front matter since Github can nicely display markdown files with this
- 2 spaces everywhere
The developer portal for stellar includes a system for displaying code-samples alongside the documentation for horizon endpoints. To recognize and process these examples, you must write them in a particular way:
- Any markdown (.md) file in a project that has a path prefix of
/docs/horizon-exampleswill be considered to be an example file. - The example file must include a
languageattribute in it's front matter. Valid values for this attribute arecurl,ruby,javascript, andgo - The file's basename must match the basename of the horizon endpoint to which it is associated. For example
docs/horizon-examples/accounts-all.mdwill be associated with the "accounts-all" horizon endpoint.
By following the rules above, your example file should get recognized by the build pipeline and slotted into the appropriate output file.
Sometimes, we may want to pass frontmatter data to js scripts on the page. Documents can specify "client data" in front matter. The term client refers to the browser. The clientData key in the front matter of a document will be converted to JSON and put in the web page as a js variable window.clientData. The clientData must be an object in order to successfully appear in the html.
[00:49:37] Error: ENOENT: no such file or directory, open '/app/layouts/plans.handlebars'This happens when you add a new directory in a docs folder in one of the repos that stellar/developers processes. If you don't want any of the docs in the directory to be included in the developers site, you can add your directory to the excluded_dirs in gulp/enhance.js:addSection.
Please read the contributing guide to learn more about how to contribute to the developer portal. For contributions to docs, please put contributions in their respective repositories.
This project is licensed under Apache License Version 2.0. For more information, refer to the LICENSE.txt file.