https://github.com/softlayer/githubio_source
Templates files for generating softlayer.github.io
https://github.com/softlayer/githubio_source
Last synced: 4 months ago
JSON representation
Templates files for generating softlayer.github.io
- Host: GitHub
- URL: https://github.com/softlayer/githubio_source
- Owner: softlayer
- License: other
- Created: 2015-11-11T15:36:58.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2025-08-15T22:32:42.000Z (6 months ago)
- Last Synced: 2025-08-16T00:31:44.019Z (6 months ago)
- Language: CSS
- Homepage:
- Size: 329 MB
- Stars: 1
- Watchers: 11
- Forks: 11
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# SoftLayer Code Examples
This is the source to build [SLDN](https://sldn.softlayer.com) with [hugo](https://github.com/spf13/hugo/)
## Building SLDN
This repository has a copy of the Hugo binaries in the `bin` directory, and those should be used to build the site, as newer versions of Hugo might not build it properly.
Just use the right binary for your OS.
- Linux is `bin/hugo`
- Windows is `bin/hugo.exe`
- Mac is `bin/hugo_mac`
### Updating `/content/reference`
This section is updated by the `bin/generateSLDN.py` python script (requires Python 3.8+)
`python bin/generateSLDN.py --download`
This script will do the following:
1. Download and parse the SLDN metadata from https://api.softlayer.com/metadata/v3.1
2. Create any needed service/method/datatype stub files
3. Generate any of the needed magic ORM methods that don't technically exist in the metadata.
Running `python bin/generateSLDN.py` without the `--download` option will simply re-parse the `data/sldn_metadata.json` file, creating and updating template fies as needed. This is useful if you want to test out changes that don't exist in the real metadata, or build the internal API documentation.
If services/datatypes are REMOVED from the metadata, this might cause issues with the hugo site generation. To fix this, simply remove the reference content and regenerate from the metadata.
`rm -rf content/reference/datatypes content/reference/services; python bin/generateSLDN.py`
### Testing Changes Locally
To view any changes you made without publishing the content, run the following:
`./bin/hugo server -d html`
This will create a local webserver available at http://localhost:1313/ and keep the generated HTML in the `html` directory, which is useful if you need to inspect the raw files for whatever reason.
### Publishing
By default https://sldn.softlayer.com ( source is on https://github.com/softlayer/softlayer.github.io) is updated by a GitHub action ([Publish Action](https://github.com/softlayer/githubio_source/actions/workflows/publish.yml)), which still requires a merged pull request on the softlayer.github.io repo, but is otherwise automated.
If you want to do this manually, you will need to checkout a copy of https://github.com/softlayer/softlayer.github.io (lets say to `../softlayer.github.io`) and run the following command:
```bash
./bin/hugo -d ../softlayer.github.io -v
```
Commit and push your changes, merge to master, and wait a few minutes.
## Directory Structure
- `.github/` All the Github actions and other github related data
- `bin/` Binaries and scripts needed for the site
- `content/` Content files that represent pages and other content on the site
+ `reference/` The auto generated documentation reference material. *Do not manually edit these files*
+ `release_notes/` Release Note blog posts, sorted into directories by year, titled by date published.
+ `*/` Everything is is grouped into language specific example blog posts.
- `data/` Contains the formatted metdata from SLDN. *Do not manually edit this file*
- `layouts/` The hugo templates that drive how pages are rendered into HTML
+ `reference/` These layouts are specific to the `reference` content
+ `partials/` These pare bit of pages that go in different sections, like Headers and Footers.
+ `_default` Layouts to use when no other is specified
+ `release_notes` Layouts specific to the release notes
- `static/` Javascript and CSS type files, other static content
- `config.toml` The main config for Hugo
## Docker
I version SLDN by dates, so I keep the dates in the container tag, you can change `20250526` to `latest` or whatever when building locally.
```bash
# To be able to pull from IBM private registry
$> ibmcloud cr login --client podman
$> podman build . -t sldn:20250526
$> podman run -p 1313:1313 sldn:20250526
```
Site will be available on `http://localhost:1313`
## Making Changes.
Files in the /content/reference section are automatically generated and shouldn't be modified by hand. Otherwise, simply creating a pull request for changes is usually sufficient. See the [CONTRIBUTING](https://github.com/softlayer/githubio_source/blob/master/CONTRIBUTING.md) guide for more specific details.
### Content Template
Below is a template to use when making new content.
`````
---
title: "Your Title"
description: "This will show up in the list view, and should contain a few keywords for easy searching.."
date: "YYYY-MM-DD"
classes:
- "SoftLayer_Account"
tags:
- "users"
- "permissions"
---
# Markdown From here on out](#title-one-link) {#title-one-link .anchor-link}
Your content goes here
Code examples should have the language explicitly set
```python
def some_function():
pass
```
`````
This project uses goldmark to parse these files. See [CommonMark](https://spec.commonmark.org/0.29/) project details for support notations.
### Tips
#### Heading Links / Anchor Links
To add a link to a heading use a heading like this:
```
[Title One](#title-one-link) {#title-one-link .anchor-link}
```
The `.anchor-link` bit adds a css class to the title, so that the link goes to the right location on the page, with a offset for the header.
#### Tags
Always a good idea to check [softlayer.github.io/tags](https://github.com/softlayer/softlayer.github.io/tree/master/tags) for existing tags and add onto those instead of making new ones where possible.
#### Classes
Any main classes your examples uses should be included. Helpful in searching.
## Requesting Examples
If you ever find yourself wishing there was an example of how to do something in the SoftLayer API, please make a github issue on the [githubio_source](https://github.com/softlayer/githubio_source/issues) repository. We are always on the look out for more content ideas!
# OpenAPI Spec Generation
You should be in the githubio_source directory first before running these commands.
First download the metadata. You can use `--clean` option to remove any other files in the directories as well. Sub directories should be created automatically.
```
$> python bin/generateOpenAPI.py --download
```
[OpenAPI CLI](https://openapi-generator.tech/docs/installation) Can be used to generate HTML or whatever from this document.
```
$> java -jar openapi-generator-cli.jar generate -g html -i static/openapi/sl_openapi.json -o static/openapi/generated/ --skip-operation-example
```
`--skip-operation-example` is needed otherwise the generator will run out of memory trying to build examples.
`./bin/generateOpenAPI-multiFile.py` can be used for a multi-file output if one file is too much to deal with.