{"id":15221916,"url":"https://github.com/googlecloudplatform/proto-gen-md-diagrams","last_synced_at":"2025-10-19T00:58:06.492Z","repository":{"id":65761886,"uuid":"597246862","full_name":"GoogleCloudPlatform/proto-gen-md-diagrams","owner":"GoogleCloudPlatform","description":"A utility for generating Markdown documentation for Protocol Buffers that include Mermaid UML Diagrams.","archived":false,"fork":false,"pushed_at":"2024-06-19T16:11:17.000Z","size":710,"stargazers_count":59,"open_issues_count":8,"forks_count":17,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-12-18T08:41:16.476Z","etag":null,"topics":["documentation","markdown","protobuf","protocol-buffers"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleCloudPlatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-02-04T00:42:52.000Z","updated_at":"2024-12-16T10:28:33.000Z","dependencies_parsed_at":"2023-03-24T06:34:50.346Z","dependency_job_id":"17190af3-a4ca-426b-8a02-8a040012abcc","html_url":"https://github.com/GoogleCloudPlatform/proto-gen-md-diagrams","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fproto-gen-md-diagrams","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fproto-gen-md-diagrams/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fproto-gen-md-diagrams/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fproto-gen-md-diagrams/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleCloudPlatform","download_url":"https://codeload.github.com/GoogleCloudPlatform/proto-gen-md-diagrams/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237243005,"owners_count":19278060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","markdown","protobuf","protocol-buffers"],"created_at":"2024-09-28T15:08:53.724Z","updated_at":"2025-10-19T00:58:06.402Z","avatar_url":"https://github.com/GoogleCloudPlatform.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Proto Gen MD Diagrams\n\n![build](https://github.com/GoogleCloudPlatform/proto-gen-md-diagrams/actions/workflows/main.yml/badge.svg)\n![coverage](https://github.com/GoogleCloudPlatform/proto-gen-md-diagrams/actions/workflows/coverage.yml/badge.svg)\n![coverage](coverage.svg)\n\nThis utility package is a compiled Go program that reads a protobuf\nsource directory and generates Mermaid Diagrams in \u003cprotobuf-file-name\u003e.md files\nin each directory, or the output directory with the given tree structure.\n\n\u003e NOTE: Only Proto 3 syntax is supported.\n\nThis utility was created to ease documentation generation of complex\nProtobuf libraries to visualize models and services described in a Protocol buffers.\n\nIf you find this useful, awesome! If you find a bug, please contribute a patch,\nor open a bug. Please follow the [Contributing](CONTRIBUTING.md) guidelines.\n\n## Test Input and Output\n\n### Build and test\n\n#### Using Native Go\n\n```shell\ngo build \u0026\u0026 go test ./...\n./proto-gen-md-diagrams -d ./pkg/proto/data/test/\n```\n\n#### Using Bazel\n\nSince Bazel is CI/CD workflow program it compiles for all targets.\n\n```shell\nbazel build //... \u0026\u0026 bazel test //...\n\n# Linux \nbazel-bin/proto-gen-md-diagrams-linux-x86_64\n\n# OS X X64\nproto-gen-md-diagrams-osx-x86_64\n\n# OS X Apple Silicon\nbazel-bin/proto-gen-md-diagrams-osx-arm64\n\n# Windows\nbazel-bin/proto-gen-md-diagrams-win-x86_64\n```\n\n| Input File                                                             | Output File                                                               |\n|------------------------------------------------------------------------|---------------------------------------------------------------------------|\n| [Location Protobuf](pkg/proto/data/test/location/model.proto)          | [Location Markdown](pkg/proto/data/test/location/model.proto.md)          |\n| [Location Service Protobuf](pkg/proto/data/test/service/service.proto) | [Location Service Markdown](pkg/proto/data/test/service/service.proto.md) |\n\n## Building\n\n### Go Lang\n\n```shell\ncd proto-gen-md-diagrams\n// Build\ngo build \u0026\u0026 go test ./...\n```\n\n## Use and Options\n\n```shell\n./proto-gen-md-diagrams -h\n\nUsage of ./proto-gen-md-diagrams:\n  -d string\n        The directoryFlag to read. (default \".\")\n  -debugFlag\n        Enable debugging\n  -o string\n        Specifies the outputFlag directoryFlag, if not specified, the processor will write markdown in the proto directories. (default \".\")\n  -r    Read recursively. (default true)\n  -v    Enable Visualization (default true)\n  -w    Enable writing output (default true)\n  -md   Enable pure MD output (default false)\n\n  \n./proto-gen-md-diagrams -d test/protos\n```\n\n## Quick Example\n\n### Protobuf Input\n\n```protobuf\n// A physical location that can be described with either an address\n// or a set of geo coordinates.\nmessage PhysicalLocation {\n  // A postal address for the physical location.\n  message Address {\n    // Address type is used to identify the type of address.\n    enum AddressType {\n      RESIDENTIAL = 0; // A residential address\n      BUSINESS = 1; // A business address\n    }\n    // First line of the address\n    string line1 = 1;\n    // Second line of the address\n    string line2 = 2;\n    // Third line of the address\n    string line3 = 3;\n    // The city or township\n    string city = 4;\n    // The state or province\n    string state = 5;\n    // The postal code\n    string zipcode = 6;\n    // The type of address\n    AddressType type = 7;\n    // Reserved for future use\n    reserved 8 to 20;\n  }\n  // The timestamp the record was created\n  google.protobuf.Timestamp created = 1;\n  // The mailing address of the location\n  Address address = 2;\n  // Longitude degrees\n  int32 longitude_degrees = 3 [json_name = 'lng_d'];\n  // Longitude Minutes\n  int32 longitude_minutes = 4 [json_name = 'lng_m'];\n  // Longitude Seconds\n  int32 longitude_seconds = 5 [json_name = 'lng_s'];\n  // Longitude Degrees\n  int32 latitude_degrees = 6  [json_name = 'lat_d'];\n  // Latitude Minutes\n  int32 latitude_minutes = 7  [json_name = 'lat_m'];\n  // Latitude Seconds\n  int32 latitude_seconds = 8  [json_name = 'lat_s'];\n  // Latitude Direction Code\n  string latitude_direction_code = 9  [json_name = 'lat_dir_code'];\n  // Altitude in Meters\n  double altitude_meters = 10  [json_name = 'alt_m'];\n  // Additional Meta Data\n  map\u003cstring, string\u003e meta = 11;\n  // Names for the location\n  repeated string names = 12 [json_name = 'names'];\n}\n```\n\n## Markdown Output\n\n### Diagram\n\n```mermaid\nclassDiagram\ndirection LR\n\n%% A physical location that can be described with either an address or a set of geo coordinates.\nclass PhysicalLocation {\n  + Address address\n  + double altitude_meters\n  + google.protobuf.Timestamp created\n  + int32 latitude_degrees\n  + string latitude_direction_code\n  + int32 latitude_minutes\n  + int32 latitude_seconds\n  + int32 longitude_degrees\n  + int32 longitude_minutes\n  + int32 longitude_seconds\n  + Map\u003cstring,  string\u003e meta\n  + List\u003cstring\u003e names\n}\nPhysicalLocation --\u003e `Address`\nPhysicalLocation --\u003e `google.protobuf.Timestamp`\nPhysicalLocation --o `Address`\n\n%% A postal address for the physical location.\nclass Address {\n  + string line1\n  + string line2\n  + string line3\n  + string city\n  + string state\n  + string zipcode\n  + AddressType type\n}\nAddress --\u003e `AddressType`\nAddress --o `AddressType`\n%% Address type is used to identify the type of address.\nclass AddressType{\n  \u003c\u003cenumeration\u003e\u003e\n  RESIDENTIAL\n  BUSINESS\n}\n```\n\n## Description\n\n\u003cdiv style=\"font-size: 12px; margin-top: -10px;\" class=\"fqn\"\u003eFQN: test.location.PhysicalLocation\u003c/div\u003e\n\nA physical location that can be described with either an address or a set of geo coordinates.\n\n| Field                   | Ordinal | Type                      | Label    | Description                          |\n|-------------------------|---------|---------------------------|----------|--------------------------------------|\n| address                 | 2       | Address                   |          | The mailing address of the location  |\n| altitude_meters         | 10      | double                    |          | Altitude in Meters                   |\n| created                 | 1       | google.protobuf.Timestamp |          | The timestamp the record was created |\n| latitude_degrees        | 6       | int32                     |          | Longitude Degrees                    |\n| latitude_direction_code | 9       | string                    |          | Latitude Direction Code              |\n| latitude_minutes        | 7       | int32                     |          | Latitude Minutes                     |\n| latitude_seconds        | 8       | int32                     |          | Latitude Seconds                     |\n| longitude_degrees       | 3       | int32                     |          | Longitude degrees                    |\n| longitude_minutes       | 4       | int32                     |          | Longitude Minutes                    |\n| longitude_seconds       | 5       | int32                     |          | Longitude Seconds                    |\n| meta                    | 11      | string, string            | Map      | Additional Meta Data                 |\n| names                   | 12      | string                    | Repeated | Names for the location               |\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Fproto-gen-md-diagrams","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglecloudplatform%2Fproto-gen-md-diagrams","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Fproto-gen-md-diagrams/lists"}