This orb automates the process of merging Docusaurus documentation from multiple repositories into a single target repository.

1. Clone Target Repository: Clones the target Docusaurus documentation repository to the CI environment.
2. Check for Docs: Verifies that documentation files exist in the source repository.
3. Copy Docs: Copies documentation from the source repository to the cloned target repository.
4. Move Static Content: Moves any static content to the appropriate directory in the target repository.
5. Generate category.json: Creates a _category_.json file for new documentation sections.
6. Commit and Push: Commits the changes and pushes them to the target repository.

• Streamlined documentation consolidation
• Configurable paths and labels
• Automatic _category_.json creation

• CircleCI account
• A Docusaurus documentation repository
• A Machine User with sufficent permissions in both the source and target repos

Here's a simple example demonstrating how to use the orb:

version: 2.1 orbs: publish-docs: infinitered/publish-docs@x.y.z # Replace with the actual version workflows: build_docs: jobs: - publish-docs/build_docs: description: "The description that will appear on autogenerated indexes and components." git_email: "your.ci@email.here" git_username: "Your CI Username" label: "The label that will appear in the sidebar of the docs site." project_name: 'name-of-project' source_docs_dir: "docs" source_repo_directory: "source" target_docs_dir: "docs" target_repo: "git@github.com:your-org/your-repo.git" target_repo_directory: "target" publish_to_docs_site: jobs: - publish-docs/publish_docs: description: "The description that will appear on autogenerated indexes and components." git_email: "your.ci@email.here" git_username: "Your CI Username" label: "The label that will appear in the sidebar of the docs site." project_name: 'name-of-project' source_docs_dir: "docs" source_repo_directory: "source" target_docs_dir: "docs" target_repo: "git@github.com:your-org/your-repo.git" target_repo_directory: "target" # Optional: Specify a specific SSH key fingerprint to use for git push # ssh_key_fingerprint: "SHA256:EXAMPLE00000000000000000000000000000000000"

In your source repository, static files such as images should be placed in a directory named _static_ under your docs folder. The directory structure will look like this when you run the tree command:

docs/ ├── part-one.md ├── part-two.md └── _static_ └── image.png 

During the documentation merge process, the orb will automatically move the contents of _static_ to the appropriate location in the target repository.

Before Merge:

source-repo/ └── docs/ │ ├── part-one.md │ └── part-two.md └── _static_/ └── image.png 

After Merge:

target-repo/ ├── docs/ │ └── <<project-name>> │ ├── part-one.md │ └── part-two.md └── static/ └── <<project-name>> └── image.png 

By following this convention, you ensure that all static files and documents are correctly placed in the target repository, under docs/<<project-name>> for documents and static/<<project-name>> for static files.

Clones the target documentation repository to ~/target_repo.

Commits and pushes the updated documentation to the target repository.

Clones a Docusaurus repo and adds the docs from the current repo to the target repository.

Installs Git on the CI environment.

None

Configures Git for commit and push operations.

Validates that all required parameters are set.