What
Add a new command portal:toc:new that adds a new toc file in the content folder of the current workspace (workspace can be overridden by passing a path through the --folder flag) or at the provided path with the optional --destination flag.
The generated toc file will include references of the following.
- getting-started
- endpoints
- models
- custom-content (every file present in the content folder and its subfolders will be parsed and added to the toc following the same hierarchy as the folder strucutre in the content directory)
- sdk-infra
Here is a sample toc that will be generated using this command. (Assume the content folder only contains a single markdown file named abc.md
toc:
- group: Getting Started
items:
- generate: How to Get Started
from: getting-started
- group: Guides
items:
- page: abc
file: abc.md
- generate: API Endpoints
from: endpoints
- generate: Models
from: models
- generate: SDK Infrastructure
from: sdk-infra
Two optional flags --expand-endpoints and --expand-models can be passed which will result in the toc containing individual endpoint and model references. The generated toc file will look something like this if both of these flags are passed.
toc:
- group: Getting Started
items:
- generate: How to Get Started
from: getting-started
- group: Guides
items:
- page: abc
file: abc.md
- group: API Endpoints
items:
group: Endpoint Group 1
items:
- generate:
from: endpoint-group-overview
endpoint-group: EndpointGroup1
- generate:
from: endpoint
endpoint-name: Endpoint1
endpoint-group: EndpointGroup1
- group: Models
items:
- generate:
from: model
model-name: Model1
- generate: SDK Infrastructure
from: sdk-infra
In the case the default workspace path or the provided destination path already contain a toc file, then the user will be prompted whether they want to overrite the file. However this can be bypassed by passing the --force flag.
Why
The purpose of this command is to help the user to quickly get started with preparing the toc file. It will especially help the user with adding references to all the custom content files, endpoints and models.
Future Work
In the next iterations, we can introduce more flags that allow skipping of certain type of content being referred in the toc. These commands can be as follows.
--skip-endpoints
--skip-models
--skip-getting-started
--skip-sdk-infra
--skip-custom-content
What
Add a new command
portal:toc:newthat adds a new toc file in thecontentfolder of the current workspace (workspace can be overridden by passing a path through the--folderflag) or at the provided path with the optional--destinationflag.The generated toc file will include references of the following.
Here is a sample toc that will be generated using this command. (Assume the content folder only contains a single markdown file named
abc.mdTwo optional flags
--expand-endpointsand--expand-modelscan be passed which will result in the toc containing individual endpoint and model references. The generated toc file will look something like this if both of these flags are passed.In the case the default workspace path or the provided destination path already contain a toc file, then the user will be prompted whether they want to overrite the file. However this can be bypassed by passing the
--forceflag.Why
The purpose of this command is to help the user to quickly get started with preparing the toc file. It will especially help the user with adding references to all the custom content files, endpoints and models.
Future Work
In the next iterations, we can introduce more flags that allow skipping of certain type of content being referred in the toc. These commands can be as follows.
--skip-endpoints
--skip-models
--skip-getting-started
--skip-sdk-infra
--skip-custom-content